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Preface 


The MicroVMS Workstation Video Device Driver Manual provides a programmer with 
the necessary information for writing applications that manipulate the QVSS and 
QDSS drivers. 

It is structured to serve as both a tutorial manual that will bring an experienced 
programmer up to speed on driver concepts and as a reference manual that can be 
used for quick reference during actual application programming. 

QIOs and system routines used when programming to the driver are provided in 
reference form. Each data type used to program to the drivers is illustrated in the 
reference sections when referred to and all the data types are summarized in two 
data-type appendixes. 


Intended Audience 

The information contained in this manual is for experienced graphics programmers 
or system programmers who are writing applications directly to the driver. 


Structure of This Document 

This manual has the following structure: 

• Chapter 1 describes concepts and terms needed to understand programming to 
the driver interface. 

• Chapter 2 describes how to perform driver interface tasks that are common to 
both the QVSS and QDSS systems. 

• Chapter 3 describes the common QVSS/QDSS QIO interface. 

• Chapter 4 describes the QDSS-specific QIO interface. 

• Chapter 5 describes how to use the Drawing Operation Primitive interface. 

• Appendix A describes all QVSS/QDSS common data types. 

• Appendix B describes all QDSS-specific data types. 
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• Appendix C describes all multiplane writing modes. 

• Appendix D contains a full QVSS driver example. 

• Appendix E contains macros used to construct keyboards. 

• Appendix F contains macros used to construct compose tables. 

• Appendix G contains the default three-stroke compose table macros. 

• Appendix H contains the $QIO system service description. 

• Appendix I contains the DEC multinational character set table. 

Associated Documents 

The following Micro VMS manuals are related to this manual: 

• MicroVMS Workstation Graphics Programming Guide 

• MicroVMS Workstation User's Guide 

• MicroVMS User's Guide 


Conventions Used in This Document 

This manual uses the following conventions in displaying the syntax requirements of 
user input to the system and in displaying examples: 


Conventions Meaning 

RETURN key The RETURN key is not always shown in formats and 

examples. Assume that you must press RETURN after typing 
a command or other input to the system unless instructed 
otherwise. 

CTRL key The word CTRL followed by a slash followed by a letter means 

that you must type the letter while holding down the CTRL 
key. For example, CTRL/B means hold down the CTRL key 
and type the letter B. 
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Conventions 

Meaning 

Lists 

When a format item is followed by a comma and an ellipsis 
you can enter a single item or a number of those 
items separated by commas. When a format item is followed 
by a plus sign and an ellipsis (+...), you can enter a single 
item or a number of those items connected by plus signs. If 
you enter a list (more than one item), you must enclose the 
list in parentheses. A single item need not be enclosed in 
parentheses. 

Optional items 

An item enclosed in square brackets ([ ]) is optional. 

Key Symbols 

In examples, keys and key sequences appear as symbols such 
as fPF^ and Ictrl/zI . 

Ellipsis 

A vertical ellipsis indicates that some of the format or example 
is not included. 

Delete Key 

The key on the VT200 series terminal keyboard that performs 
the DELETE function is labeled <3] . Assume that DELETE 


in text and examples refers to both the VTIOO and VT200 series 
delete keys. 

Examples 

Examples show both system output (prompts, messages, and 
displays) and user input. User input is printed in red. 










New and Changed Features 


The following changes have been made for Version 3.0 of the Micro VMS Workstation 

software: 

• The QDSS driver is available — only on systems with QDSS hardware. The 
QDSS driver permits you to draw multiplane (color) images through the use of 
the hardware-assisted Drawing Operation Primitive (DOP) interface. The QDSS 
system also uses a QIO interface. Read Chapters 1 and 2 for an overview of the 
driver. 

• New QDSS-specific QIOs — see Chapter 4. 

• New DOP interface — see Chapter 5. 

• New UISDC routines for use with the DOP interface — see Chapter 5. 




Chapter 1 

Video Device Driver Introduction 


This chapter provides an introduction to the concepts and terms this manual uses to 
describe how to write an application that interacts with the QVSS and QDSS video 
device drivers. Once you have read this chapter, you will know which programming 
interface your application should address, and you will be ready to proceed to the 
task-oriented Chapter 2. 

This chapter describes: 

• An overview of the two available video device drivers (QVSS and QDSS). 

• How you determine which programming interface your application should 
address. (Your application may not need to write to a device driver.) 

• How the two drivers address the screen. 

• How the drivers use memory. 

• How an application accesses a driver. 

Some of the concepts and terms described in the following sections apply to both 
drivers, while others are specific to one driver. The manual clearly notes sections 
that describe specific concepts. 


1.1 Overview of the Drivers 

A VAXstation may have one of the following two video device drivers: 

• The Q-Bus Video Subsystem (referred to as QVSS) 

• The Q-Bus Device Subsystem (referred to as QDSS) 

Both drivers allow you to create graphics applications that use the VAXstation 
features. However, each driver requires unique hardware, so a VAXstation can be 
configured with either a QVSS driver or a QDSS driver, but not both. 
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The device drivers provide a common interface to VAXstation hardware functions 
such as manipulating memory and writing to the screen. By using a common 
interface, applications can guarantee that the hardware is accessed in a uniform 
fashion. All VAXstation software uses the driver to access the hardware, either 
directly or indirectly. Figure 1-1 illustrates the layered relationship of applications, 
VAXstation software, the device driver, and VAXstation hardware. 

Figure 1-1 The Driver Interface 
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1.1.1 Driver Differences 

There are a number of differences between the QVSS driver and the QDSS driver, 
the primary ones being the use of color, the method of bitmap manipulation, and the 
ability to provide alternate windowing systems. 

Color 

The QVSS device driver is designed for use with a one-plane memory system. It is 
therefore restricted to the use of black and white images. 

The QDSS device driver is designed for use with multiplane memory systems, so the 
QDSS driver has the capability to draw color and gray-scale images. 

Bitmap Manipulation 

The QVSS driver only supports direct bitmap manipulation. If you write an 
application to the QVSS driver, your application is completely responsible for 
drawing to the bitmap. 
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The QDSS driver provides a number of drawing operations that make drawing to 
the bitmap easier and faster. These operations are drawing operation primitives 
(referred to as DOPs) and are described in detail in Chapter 5. DOPs use additional 
multiplane hardware to accelerate drawing. 

Alternate Windowing 

The QVSS driver provides a way to alternate between the UIS windowing system 
and a windowing system of your own design. Both windowing systems share video 
memory when you use alternate windowing systems. 

The QDSS driver does not currently provide a way to alternate between windowing 
systems; it supports only one windowing system at any given time. 


1.2 Which Interface to Choose 

When writing an application, you must determine which level of interface your 
application should address. As shown in Figure 1-1, your application may address 
the system at the UIS level, the driver level, or even the hardware level. Each 
successive level downward increases the degree of control your application has while 
increasing the amount of work your application must perform. 

UIS and UlSDC Interface 

UIS, the VAXstation graphics operating system, provides a basic set of graphic 
primitive, color, and windowing routines to use when writing high-level graphics 
applications. UIS routines use a world coordinate system. 

If your application requires direct access to display coordinates, it can use the UISDC 
routines. The UISDC routines allow you to manipulate primitives in a device¬ 
dependent manner. The UIS and UISDC routines are described in The MicroVMS 
Workstation Graphics Programming Guide. 

If the UIS interface provides all the necessary functionality for your application, 
address the UIS interface. 

Driver Interface 

Your application can bypass the UIS/UISDC interface and manipulate the driver 
directly. This feature allows you to create graphics packages tailored to your specific 
needs. For example, you can design your own windowing system, or you can 
provide your own drawing routines. 

This manual provides the information necessary for an application to access either 
the QVSS or QDSS driver directly. The manual is intended for system programmers 
with a working knowledge of basic graphic concepts. 
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Hardware Interface 

It is also possible to bypass both the UIS interface and the driver interface and 
directly address the hardware. If your application has no need for a windowing 
system, you may wish to consider writing directly to the hardware. How to address 
the hardware directly is beyond the scope of this manual. Refer to the hardware 
documentation for information about the hardware interface. 


1.3 How the Drivers Work 

This section contains a general description of how the drivers work. It introduces 
many concepts and terms that must be understood before you can attempt to write 
to the driver interface. 

1.3.1 Defining Regions on the Screen 

Both drivers address rectangular portions of the screen referred to as regions. The 
QDSS driver accesses regions of the screen as viewports (see Section 1.3.10 for more 
information on viewports). Your application defines the addressable regions of the 
screen using QIOs that are part of the driver interface. 

For the driver to define a region, your application must associate the region with a 
unique channel. The channel provides a logical path connecting the application to 
the device driver. To obtain a unique channel number for a region, call the $ASSIGN 
system service before you define the region. 

When your application defines a region, it associates the region with one of the 
following events: 

• Cursor pattern 

• Keyboard input 

• Pointer button transition 

• Pointer movement 

• Viewport (QDSS only) 

The QIO you use to define the region determines the type of event the driver 
associates with the region. For example, if you want the driver to associate a 
region with button transitions, you should define the region with the Enable Button 
Transition QIO. 

When you define a region and associate it with an event, you can also specify an 
action to take place when the event is detected in that region by specifying the 
address of an AST action routine as a parameter of the region-defining QIO. For 
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example, you can define a region, associate it with a button transition, and specify 
that the region be erased when the driver detects the specified transition. 

It is the job of the driver to detect when an event occurs and to ensure that the 
proper action takes place when it does. Section 1.3.4 describes how the drivers 
manage regions and events. 

1.3.2 Driver Communication Mechanisms 

An application can access either driver, using a QIO interface. 

An application may also access the QDSS driver, using a mechanism referred to as 
the request queue. The request queue interface is QDSS specific. 

1.3.2.1 The QIO Interface 

The QIO interface is the method of access that is common to most drivers. The 
QVSS and QDSS drivers provide a number of QIOs that perform driver-specific 
functions, such as initializing the screen, defining a pointer movement region, or 
performing a bitmap copy. 

While the QIO interface is common to both drivers, some QIOs are QDSS-specific. 
Any driver QIO can be used with the QDSS driver, while the QIOs that apply to 
both the QVSS and QDSS drivers are a subset of the entire QIO interface. The 
structure of this manual reflects this fact: Chapter 3 describes in detail the subset of 
QIOs that apply to both the QVSS and QDSS drivers; Chapter 4 describes the QIOs 
that apply only to the QDSS driver. 

The majority of the QIOs are input functions. They are typically called with 
IO$_SETMODE specified as the function parameter. In these QIOs, the PI parameter 
actually serves as the distinguishing function code. 

The remaining QIOs are output functions. They are typically called with 
IO$^SENSEMODE specified as the function parameter. Again, in these QIOs, 
the PI parameter actually serves as the distinguishing function code. 

While the QIO interface permits a wide range of functions, some may be grouped 
together in functional categories. The following sections contain general descriptions 
of those categories. (See Chapters 3 and 4 for complete descriptions of all QIOs.) 

Tracking Associated Events and Regions 

Several input QIOs permit an application to construct list entries. The QVSS and 
QDSS drivers keep track of which regions are associated with which events by 
keeping lists — one list for each type of event. Typically, when you define a region, 
you use an input QIO that passes the driver the following information: 

• Region description 


• Associated event 
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• Address of an AST routine that defines the action to take when the event occurs 

The driver uses this information to construct a list entry, which it places on the 
appropriate list. When an event occurs, the driver searches the lists and triggers the 
AST pointed to by the appropriate list entry. Section 1.3.4 elaborates on how the 
driver constructs and manages lists. 

Returning System Information 

The output QIOs permit your application to get information from the system. The 
Get System Information QIO returns the system information block, which describes 
the state of the system such as: 

• Dimensions (and subdivisions) of video memory 

• Current pointer position 

• Current button status 

The system information block differs slightly depending on whether you are on a 
QVSS system or a QDSS system. The QDSS system block contains all the same 
fields as the QVSS system block, but includes additional fields. Appendixes A and B 
illustrate and describe the structures of both system blocks. (On the QVSS system, 
the information block is referred to as the QVB; on the QDSS system, it is referred to 
as the QDB.) 

You may also inquire about the characteristics of the current keyboard, using the Get 
Keyboard Characteristics QIO. 

On QDSS systems only, you can obtain a viewport ID for use in subsequent 
operations, as well as color map information. See Section 1.3.10 for information 
about viewports. 

Queue Manipulation 

This section applies only to QDSS systems. 

Several QDSS-specific output QIOs are used for manipulating the QDSS-specific 
queues: the request queue, the return queue, and the deferred queue. These QIOs 
permit an application to stop and start processing on the queues. The request queue 
is briefly described in the next section. A full description of the three queues and 
their interaction appears at the end of this chapter. 
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1.3.2.2 The Request Queue Interface 

This section applies only to QDSS systems. 

The request queue interface allows your application to perform drawing operations 
and to manipulate queues. The request queue interface involves less overhead than 
the QIO interface. 

To use the request queue, your application must use drawing operation primitives 
(DOPs). A DOP is a data structure that contains the data needed to perform a 
drawing operation. Your application submits DOPs to the request queue for 
execution. The request queue is a double-linked list of all the DOPs waiting for 
execution. The order in which the DOPs are placed on the queue is the order in 
which the DOPs are executed (drawing is performed). 

Section 1.3.11 describes the QDSS-specific queues in detail. Chapter 5 describes how 
to use DOPs. 

1.3.3 How the Drivers Use Memory 

To write to the screen, an application actually writes to video memory. The driver 
then maps the video memory to the screen. Understanding how the drivers use 
memory is essential to understanding how to program to the drivers. 

1.3.3.1 How QVSS Uses Video Memory 

The VAXstation display area is 1024 x 864 pixels. The full QVSS video memory is a 
1024 X 2048-bit block of memory or, to correspond to the screen, 2048 lines of 1024 
pixels. QVSS uses a data structure referred to as the scanline map to map lines of 
video memory to lines on the screen. 

The scanline map is a contiguous-word index into video memory, which indexes the 
entire screen display area (864 lines). Each entry in the scanline map is a 0-relative, 
16-bit word value that functions as an index into video memory. The first entry in 
the scanline map locates the first line of the screen display, the second entry contains 
the second line, and so forth. For each bit that is set on an indexed line of video 
memory, the driver sets a corresponding pixel on the display screen. 

However, since a maximum of 864 lines of video memory can be displayed at any 
one time and total video memory is 2048 lines, QVSS video memory is referred to 
in two sections; onscreen and offscreen memory. Onscreen memory is any portion of 
video memory that is currently being displayed. Since the largest VAXstation display 
is 864 lines, that is the maximum size of onscreen memory. 

Offscreen memory is the 1184 lines of video memory that are not displayed. Offscreen 
memory may be used to store images or fonts that are not currently being displayed. 
It also plays an important role in the handling of occlusion (see Section 1.3.9). 
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NOTE: On a VAXstation 2000 monochrome monitor, the system video memory 
is slightly different. One screen of video memory is available (1024-bit x 864-bit). 
Also, the hardware scanline map is not available. The system always displays 864 
scanlines of video memory with the first scanline starting at the first byte of video 
memory. Therefore, you cannot change the scanline order. 

Figure 1-2 illustrates the layout of QVSS memory. 

Figure 1-2 QVSS Video Memory and Scanline Map 
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The Hardware Cursor 

The cursor that appears on the screen is defined by a separate block of hardware 
memory. This block is 16 x 16 bits on systems with a single-plane cursor (QVSS) 
and is 16 x 32 bits on systems with a multiplane cursor (QDSS). This block stores the 
bitmap image of the cursor pattern. It is not part of video memory. The driver uses 
the hardware to "overlay" the video signal sent to the screen (see Figure 1-2). This 
arrangement eliminates the need for a save and restore operation in video memory 
each time the cursor moves or a write to video memory occurs. Section 2.8 describes 
how to define cursor patterns. 
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The Scanline Map 

Note that the scanline map need not index consecutive lines of video memory. That 
is, an object may be represented in nonconsecutive lines in video memory (because 
there is not enough consecutive memory), yet appear on consecutive lines on the 
screen. Figure 1-3 illustrates how the scanline map properly maps to the screen two 
objects represented in nonconsecutive memory. 
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Figure 1-3 Scanline Map Mapping Nonconsecutive Memory 
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Video Memory 



Accessing QVSS Video Memory 

QVSS permits direct bitmap access, meaning that an application can directly set bits 
in the video memory. 

An application can write to QVSS video memory using any suitable computer 
language (FORTRAN, MACRO, and so forth). However, before writing to video 
memory, an application must issue the Get System Information QIO to obtain the 
QVSS system block (QVB), The QVB contains all the information an application 
needs to write to video memory. See Appendix A for a complete description of the 
QVB. 

An application should issue a request for the QVB for each process. The address of 
the system block does not change. Therefore, a process can obtain the QVB address 
once, and continue to reference fields in the QVB until the process terminates. 
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1.3.3.2 How QDSS Uses Video Memory 

The largest possible VAXstation display is an 1024-pixel by 864-pixel area or 864 
lines that are 1024 pixels in length. The full QDSS video memory is a 2048-pixel by 
1024-pixel block of memory or, to correspond to the screen, 2048 lines that are 1024 
pixels in length. QDSS maps video memory directly to the screen. So, in the case of 
the largest display, it maps the first 864 lines of video memory to the screen. This 
portion of video memory is referred to as onscreen memory. 

The remaining 1184 lines of video memory are referred to as offscreen memory. 
Offscreen memory plays an important role in the handling of occlusion (see 
Section 1.3.9.) The offscreen portion of the video memory is further divided into 
the following fixed-length sections: 

• Scrolling save area 

• Free_l area 

• Bitmap storage area 

Figure 1-4 illustrates the layout of QDSS memory and shows relative coordinates for 
the beginning and end of each area. 

Figure 1-4 QDSS Video Map 
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Note that the lower left-hand corner of onscreen memory is considered to be the 
coordinate (0,0), corresponding to the lower left-hand corner of the display. (All 
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viewports are defined relative to this base.) Therefore, any coordinate with a negative 
Y element is in offscreen memory. 

Scroll Area 

The driver uses the scroll area to process downward scrolls. This area is reserved for 
the driver and cannot be accessed by the application. 

Free_1 Area 

Free_l is the largest area of free memory. An application can use this memory for 
any operations it wishes to perform. 

Bitmap Storage Area 

The driver uses the bitmap area to store bitmaps—fonts, images, and pattern fills. 
The area consists of a 70-line by 1024-bit block of memory for each plane of memory 
on the system. Some planes partition these 70-line blocks of memory into two 
35-line sections. This permits more fonts to remain in memory. An application uses 
this area to load any defined bitmaps stored in VAX memory. 

You load the information in VAX memory into the bitmap storage area by using the 
Load Bitmap QIO or the UISDC$LOAD JITMAP routine. 

If a particular bitmap cannot fit into the bitmap storage area, it is the application's 
responsibility to partition the information into one 70-line section on a single-plane 
image or two 35-line sections for multiplane images. 

Accessing QDSS Video Memory 

QDSS does not permit direct bitmap access. You draw to video memory using the 
drawing operation primitive (DOP) interface and you may copy images to video 
memory using Read Bitmap and Write Bitmap QIOs. 

Viewports — Any operation the QDSS driver performs must be directed to the 
screen by way of a viewport. An application can create viewports or use the default 
systemwide viewport (the full screen). See Section 1.3.10 for more information about 
viewports. 

Exclusive Bitmap Access — Your application may require exclusive bitmap access 
to all or part of video memory. When you perform an exclusive-access operation, no 
other operations should access onscreen memory. Since the QDSS driver controls 
all access to onscreen memory, an application must always notify the driver of a 
pending exclusive bitmap operation. 

Bitmap Transfers — The QDSS driver can perform three types of bitmap transfers: 
VAX memory-to-bitmap, bitmap-to-VAX memory, and bitmap-to-bitmap. Transfers 
are executed using the QIO interface and require exclusive bitmap access for 
synchronization. 
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The QDB — An application may issue the Get System Information QIO to obtain the 
QDSS system block (QDB). The QDB contains information about video memory that 
an application needs to manipulate video memory. See Appendix B for a complete 
description of the QDB. 

1.3.4 How the Drivers Track Screen Events 

The QVSS and QDSS drivers keep track of events that occur on the screen by 
keeping lists — a list for each type of event. There are four events for which the 
drivers keep lists: 

• Cursor pattern change 

• Keyboard entry 

• Pointer button transition 

• Pointer movement 

The drivers also manage a user entry list that your application can use for general 
storage purposes. 

Note that the driver associates each of the first three events listed with a specific 
region. The keyboard entry event, although not actually associated with a specific 
region, can be thought of as being associated with the entire screen. 

When you define a region with a QIO, the driver uses the information you pass it 
to construct a list entry which it places on the appropriate list. List entries typically 
contain the following: 

• The region definition 

• The address of any AST routine defined to take action when the event occurs 

• Any AST parameter (token) 

When an event occurs the driver searches the appropriate list using the region 
definition to identify which list entry's AST to issue. For example, if a button 
transition is detected, the driver searches the button transition list to find if the 
region that it occurred in has a button transition AST enabled. In the case of the 
keyboard entry, the first entry on the keyboard list is always invoked. 

The following sections provide a brief summary of how the drivers handle each type 
of event. 



Video Device Driver Introduction 1-13 


1.3.5 Cursor Pattern List 

The cursor pattern list is used to determine the pattern of the cursor for a region. 
You can define the cursor shape and hot spot for a region using the Define Pointer 
Cursor Pattern QIO. The list entry contains the following: 

• Unique channel ID 

• The address of a 16 X 16 (16-word) bitmap defining the shape of the cursor 

• Cursor hot spot, a point on the 16- by 16-pixel cursor that defines the exact 
placement of the cursor image 

• Cursor background style 

• Region definition 

See the Define Pointer Cursor Pattern QIO description for more details. 

When the driver detects cursor movement, it searches the cursor pattern list for the 
appropriate ASTs to deliver. If a cursor pattern is to be changed, the bitmap image 
of the new pattern is located and loaded into the hardware. The new pattern is then 
superimposed on the appropriate area of the screen. 

1.3.6 Keyboard Entry List 

The driver uses the keyboard entry list to determine the process to which it should 
deliver keyboard input. An application can request keyboard ownership by using 
the Enable Keyboard Input QIO. The driver then delivers input keystrokes to the 
process by way of AST routines you specify in the QIO. Keyboard list entries are 
not associated with regions. There is one keyboard associated with each assigned 
channel. 

Each keyboard list entry contains the following: 

• A unique channel ID 

• An AST service routine address 

• Address of the longword that receives an input token when the AST routine is 
called 

See the Enable Keyboard Input QIO description for more details. 

Unlike other lists, when a keyboard event occurs, the first entry on the list is invoked. 
The list is not searched. The driver always inserts the active keyboard entry at the 
beginning of the list. 

A keyboard becomes active by popping or cycling operations. Cycling moves the 
current first entry on the list to the back of the list. Figure 1-5 illustrates cycling. 
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Figure 1-5 Cycling the Keyboard List 
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Popping moves an entry from any position to the front of the list. 

1.3.7 Pointer Button Transition List 

The driver uses the pointer button transition list to determine what action to take 
upon pointer button transitions. A button transition may be either up or down and 
is detected by the hardware. 

A button transition event is triggered when the pointer button is pressed or released 
within a region defined with the Enable Button Transition QIO. Each pointer button 
transition list entry contains the following: 

• Unique channel ID 

• Address of the AST 

• Region definition 

• Address of the longword to receive the input token indicating which pointer 
button is activated 

When a pointer button transition occurs the driver searches the pointer button 
transition list for an entry describing the new region. If one is found, the action 
taken when a pointer button is pressed is determined by the AST routine defined for 
that region. A token is passed to the specified AST routine to signal which button 
made a transition, and the type of transition (up or down). See the Enable Button 
Transition QIO description for details on how button transitions are represented. 

If regions for pointer button transitions overlap, priority is given to the first rectangle 
on the list. 
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1.3.8 Pointer Movement List 

The driver uses the pointer movement list to determine what action to take when 
the pointing device is moved. You may define a region in which special action can 
be taken upon pointer movement using the Enable Pointer Movement QIO. Each 
pointer motion list entry contains 

• Unique channel ID 

• Address of the AST 

• Region definition 

• Address of the longword to receive the input token indicating the current 
physical position of the pointer 

The driver searches the list comparing the current pixel position of the pointer against 
the region definitions of all list entries. The current location of the pointer determines 
what event to trigger. If regions for pointer motion events overlap, priority is given 
to the first region on the list. 

When the pointer cursor moves outside a currently active region, the AST is passed 
a special exit token of -1, to notify the process that the cursor has left the region. A 
process may wish to perform some cleanup functions when the pointer leaves the 
region. 

1.3.9 Occlusion 

In a windowing system, it is possible for more than one window to address the same 
area of the screen. However, the drawing of only one window can be displayed in a 
particular area at any given time. The case when one window display occludes, or 
hides, a part or all of another display is called occlusion. 

You must write your application to handle occlusion (unless it has only one window 
or it can guarantee that windows never overlap). The QDSS driver offers some 
software support for handling occlusion. See Section 1.3.10.2. The QVSS driver, 
because it is a direct bitmap access system, does not offer any support for handling 
occlusion; that is solely the responsibility of the application. 
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1.3.10 What Is a Viewport? 

This section is QDSS-specific. 

The QDSS driver directs various operations to the screen by way of viewports. A 
viewport is a rectangular area defined within video memory. Viewports may be 
user-defined or systemwide viewports. 

A user-defined viewport can be specified anywhere in video memory. The 
dimensions of the viewport are defined by using the Set Viewport Region QIO. 
Logically, a viewport is a single rectangular region. However, in order to handle 
occlusion, you can use Set Viewport Region to define a viewport as one or a number 
of distinct update regions (see the next section). These regions together describe the 
size of the viewport and its relative location in video memory. 

The systemwide viewport is one update region that encompasses all available video 
memory and can be considered the system default viewport. If no other viewport is 
defined, all drawing operations are directed to the systemwide viewport. 

The coordinates of all drawing operations directed to a particular viewport are 
specified relative to the lower left-hand comer, or base, of the viewport. Such 
operations are said to be viewport relative. 

1.3.10.1 Viewport Update Regions 

As described above, update regions store all the coordinate information necessary to 
define a viewport. An application uses the data stmcture illustrated in Figure 1-6 
to define a viewport update region. The driver uses this information when mapping 
the viewport-relative coordinates (VRC) of the viewport to the absolute device 
coordinates (ADC) of the display. 

The coordinate information stored in an update region contains the location of the 
viewport in video memory (x^base, y_>base) and the extents of the viewport (x_min, 
y_min, x_max, and y_max). 

Figure 1-6 Viewport Update Region Data Structure 
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1.3.10.2 Using Update Regions for Occlusion 

You can define viewports that overlap the same area of onscreen memory. When 
this occurs, the portion of the viewport that is not visible is considered "occluded" 
and is hidden behind the other viewport on the screen. Since only one viewport 
can occupy an area of memory at any given time, you cannot write to the onscreen 
location of the overlapped portion of the occluded viewport. 

An application may direct writing operations to the occluded portion of the screen 
even though it cannot display them while the region is occluded. To keep track of 
any drawing operations that may be directed to an occluded portion of a viewport, 
your application must divide the occluded viewport into several update regions. The 
accessible regions are updated immediately in onscreen memory, and the operations 
to an occluded region are either performed in offscreen memory or deferred until 
memory is available. Chapter 2 describes how to handle occlusion. 

1.3.11 QDSS Drawing Operation Queues 

As stated in a previous section of this chapter, the QDSS driver provides a request 
queue interface that executes drawing operation primitives (DOPs). Chapter 5 
describes how to construct DOPs and enter them on the request queue. This section 
describes the mechanisms used for executing DOPs. 

There are three queues that are relevant to the execution of DOPs: 

• The request queue 

• The return queue (actually two queues) 

• The deferred queue 

The following sections describe each queue. 

1.3.11.1 The Request Queue 

A request queue is a doubly linked list of DOPs that have been submitted for 
execution. Each defined viewport (including the systemwide viewport) has a request 
queue associated with it. Any drawing operation to be executed within a viewport 
must be entered on that viewport's request queue. An application associates a 
viewport with a request queue by getting a viewport ID for the viewport. (This is 
done using the Get Viewport ID QIO.) The viewport ID is actually the address of the 
DOP queues data structure which contains the starting address of the request queue 
(as well as that of the return queues). See Appendix B for a full description of this 
data structure. 

You may enter a DOP on the request queue in any of the following ways: 

• Using the UISDC interface (see Chapter 5) 

• Issuing the Insert DOP QIO 
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• Using the MACRO instruction INSQUE 

At specific intervals, the driver scans all request queues checking for work. If any 
queue contains DOPs, the driver removes the DOPs from the queue and performs 
the specified operations. The order in which the packets are stored on the queue is 
the order in which the drawing operations occur. 

Certain screen management circumstances require that the processing of request 
queues be stopped. Sometimes it is appropriate to stop a single viewport's request 
queue, sometimes all viewport request queues must be stopped. The QIO interface 
provides a number of QIOs that manipulate the request queue. (A small number of 
DOPs also manipulate the request queue — in a limited way.) Chapter 2 describes 
the circumstances under which an application manipulates the request queue. 

1.3.11.2 The Return Queue 

A DOP is a data structure and must have storage allocated for it. If you were 
to process a large number of DOPs without any restrictions, they could consume all 
available system memory (or enough to cause considerable performance degradation). 

The QDSS driver provides the return queue as a way for an application to reuse 
storage allocated for DOPs. The return queue, like the request queue, is a doubly 
linked list. Once a DOP is completely processed, the driver removes it from the 
request queue and inserts it on the return queue (by simply updating the links). A 
DOP on the return queue is referred to as a free DOP. 

An application can save storage by checking the return queue for used DOP storage 
before allocating memory for new drawing operations. 

Allocating DOPs 

You allocate storage for DOPs using either the UISDC interface (see Chapter 5) or 
using memory allocation system routines. When you allocate a DOP, you allocate 
one of two fixed sizes, small or large. You define the sizes of a large and a small 
DOP by initializing the DOP size fields of the DOP queue structure and the request 
queue structure. This structure is described in Appendix B. 

All applications should first check the return queue for reusable DOP storage before 
allocating new storage. (The UISDC interface does this.) An application can force 
the driver to wait for a DOP from the return queue by using the Get Free DOPs QIO. 
One of the parameters for this QIO allows an application to specify the number of 
DOPs to wait for on the return queue before returning control to the application. The 
application can then reuse the storage by removing a DOP from the return queue. 

This feature can prevent a situation where too much system memory is allocated. 

For example, assume an application allocates 300 DOPs for processing on the request 
queue and before processing is complete needs more DOPs for additional operations. 
If the application were allowed to allocate all the additional DOPs it requires the 
application might consume all available system memory. However, specifying a high 
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number of DOPs to the Get Free DOPs QIO forces the application to halt further 
memory allocation until that number of DOPs is available for reuse. 

Actually Two Queues 

As mentioned above, DOPs are allocated in two sizes. It is only logical then that 
the return queue is actually two queues, one to which small DOPs are returned, and 
another to which large DOPs are returned. When you issue the Get Free DOPs QIO, 
you specify the number of DOPs you wish to wait for as well as the specific return 
queue. 

Alternate return queue 

By default, a return queue is associated with each viewport through the DOP queue 
structure. However, you may use an alternate return queue if you wish to share 
return queues on a per-process or systemwide basis. To do so, you specify the 
address of a return queue structure as the fourth parameter of the Get Viewport ID 
QIO when you create the viewport. The return queue section of the viewport's DOP 
queue structure is ignored in this case. See Appendix B for descriptions of these 
structures. 


1.3.12 The Deferred Queue 

When a portion of a viewport is occluded onscreen, the first option for writing to it 
is to write to an update region in offscreen memory. However, sometimes offscreen 
memory is so crowded that you cannot keep an update region in offscreen memory. 
In this case, you must save the writing operations on the deferred queue. 

The driver stores all operations directed to a portion of a viewport that is not 
currently available to the QDSS hardware on the deferred queue. Deferred queue 
operations can be executed at any time the previously occluded portion of the 
viewport becomes available. 

To prevent the deferred queue from consuming system resources, an application 
should update occluded viewports when the queue is full. The Notify Deferred 
Queue Full QIO notifies an application the deferred queue is full. The Execute 
Deferred Queue QIO executes the operations on the deferred queue. For additional 
information on deferred queue operations see Chapter 2 of this manual. 





Chapter 2 

How to Program to the Driver 


This chapter describes how to perform programming tasks that are commonly used 
when writing to the video device drivers. Tasks that are common to both drivers are 
described first. Tasks that are specific to either the QVSS or QDSS driver are clearly 
noted. 

This chapter details how specific QIOs and DOPs are used in combination to perform 
tasks. No attempt is made in this chapter to fully describe these QIOs and DOPs 
because Chapter 3 and Chapter 4 describe each function of the QIO interface in 
detail. Chapter 5 describes the DOPs that are available (on a QDSS system) for 
drawing to the display. 


2.1 Initializing the Screen 

Before an application can write to the screen, it must first initialize the screen. 
Initialization places the VAXstation screen in a known state. Once the initialization 
is complete, the application can issue additional QIOs and begin screen operations. 
Failure to initialize the screen before doing a draw operation will result in undefined 
behavior for the drawing operation. 

To initialize the screen, use the Initialize QIO. This QIO has no parameters and is 
invoked only once for each application. 
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2.2 Accessing the System Information Block 

The system information block (the QVB or QDB, depending on which type of system 
you have) is a data structure that both drivers use to store information describing 
the current state of video memory. This data structure consists of a number of fields, 
each of which is associated with a symbolic constant that is used to reference the 
field. See Appendixes A and B for a full illustration and explanation of each field in 
these data structures. 

To get the address of the system information block, use the Get System Information 
QIO. This QIO returns a descriptor that contains the address and size of the block. 
To access any field in the block, use the returned address and the symbolic constants 
defined for that field. 

How to Use the QDB 

A QDSS application may or may not need to access the QDB. If it is only using the 
UISDC DOP interface there is no need. However, under some circumstances, for 
example, if it manipulates the pointer position or requires tablet information, it may 
need system information stored in the block. Example 2-5 uses the QDB to get the 
systemwide viewport ID. 

How to Use the QVB 

Typically, before a QVSS application can perform a drawing operation, it must 
obtain specific video memory information from the QVB — the starting address of 
video memory and the address of the scanline map. A QVSS application needs the 
starting address of video memory in order to set bits (draw) in memory. It needs the 
address of the scanline map to map to the screen any lines in memory it wishes to 
display. How to use the QVB for drawing operations is described in Section 2.10. 
The following code segment shows a call that obtains the descriptor for the QVB. 

! Declare QDB descriptor and buffer 
INTEGER*4 QDBJESC(2) 


j 


! Obtain a channel for the call 
CALL SYS$ASSIGN (*SYS$W0RKSTATI0N*, 
2 CHAN,,) 


device name 
channel 
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! Get the QVB 
CODE = I0$_SENSEM0DE 
STATUS = SYSSQIOW (. 

2 y,VAL(CHAN), ! channel 

2 VoVALCCODE), ! QIO function code 

2 

2 “/oVALdOSC.QV.GETSYS). 

2 QVB.DESC,.. 

IF (STATUS .NE. 1) THEN 

CALL LIB$SIGNAL C/.VAL (STATUS)) 

END IF 

! Extract from the QVB 
CALL EXTRACT.QVB (•/oVAL(QVB_DESC(2)) . 

2 VIDEO^ADDR, 

2 SCANLINE.ADDR) 


! address of descriptor 


pass address by value 
video memory buffer 
scanline map buffer 


! * EXTRACT^QVB SUBROUTINE * 

I :|c 9(c ^ :)c ^ :lc9|c)|c 9|c :|c :|( 3|c )|( }|c :|c:(c)|c :|c 

FUNCTION EXTRACT.QVB (QVB, VIDEO, SCAN) 
IMPLICIT INTEGER*4(A-Z) 

INCLUDE ’VWSSYSDEF’ 

! Associate the predefined structure w/ QVB 
RECORD /QVB_COMMON_STRUCTURE/ QVB 

VIDEO = QVB.QVB$L_MAIN_VIDEOADDR 
SCAN = QVB.QVB$L_MAIN_MAPADDR 

RETURN 

END 


2.3 Using Channels with the Video Device Drivers 

Channel numbers are used by the drivers to identify application list entries. Recall 
the way that the drivers use entry lists; they keep track of different events by putting 
entries for the events on lists (Section 1.3.4). When an application places an entry 
on a list (using the QIO interface), it associates the entry with a channel number 
(using the chan parameter of the QIO). To obtain a unique channel number, use the 
$ASSIGN system service. 
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The channel number associated with each entry an application puts on a list must be 
unique to that list. That is, if a process creates an entry on the keyboard list using 
channel 1, it cannot create another entry on the keyboard list using channel 1. It 
must obtain another channel to create another entry. The driver uses the channel 
number to uniquely identify the entries when adding or deleting entries. 

However, the same channel number can be used across lists. For example, an 
application can create an entry on the button transition list, the keyboard entry list, 
and the cursor pattern list, each using channel 1. 


2.4 Using the Keyboard 

Driver keyboard functions permit an application to: 

• Receive keyboard input 

• Modify the keyboard characteristics of a keyboard 

• Modify keyboard character sets 

• Compose characters that do not exist as standard keys 
The following sections describe these capabilities. 

2.4.1 Receiving Keyboard Input 

To receive input from a keyboard an application must explicitly enable the keyboard 
for input using the Enable Keyboard Input QIO. Enabling a keyboard creates an 
entry on the keyboard entry list. When you enable a keyboard you may specify: 

• The address of a four longword AST specification block. The four longwords 
contain 

1. The address of an AST routine that determines what action to take when 
input is received. This type of AST is referred to as a keystroke AST because 
it is fired for each keystroke that is input. 

If no AST routine is specified, input will be stored in the typeahead buffer, 
and delivered either when an AST region is declared using the same channel 
or when a Get Next Input Token QIO is issued. 

2. An optional user-defined AST parameter that is delivered to the AST. 

3. Access mode at which to deliver the AST (maximized with the current access 
mode). 


4. A zero. 
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• The address of an AST routine that is invoked whenever the entry is made 
active (brought to the top of the list). This type of AST is referred to as a request 
AST (or control AST). It is fired only once for each entry activation. Only one 
keyboard can be active at any one time. Typically, the request AST performs any 
necessary actions that the enabled keyboard requires, for example, popping an 
obscured window so that displayed input may be seen. 

• Address of a keyboard characteristics block that describes the characteristics of 
the keyboard. Each keyboard has a set of characteristics associated with it (key 
click, auto repeat, and so on) that are defined in this data structure. You may 
choose to take the default characteristics or modify the defaults. Section 2.4.2 
discusses keyboard characteristics in detail. 

By default, an entry is placed at the top of the list when a keyboard is enabled. 
However, an application may determine the position of the entry in the list by 
specifying optional modifiers to the QIO. The modifiers can be used to: 

• Cycle the list — top entry is moved to the end of the list (QV-_CYCLE) 

• Place the entry last on the list (QV_^LAST) 

• Delete the entry (Q\L.DELETE) 

• Purge the typeahead buffer (QV__PURG-_TAH) 

Typically, an application defines one keyboard for each window. However, it may 
define the characteristics of each keyboard differently from window to window. This 
feature permits you to create "virtual" keyboards. Although there is one physical 
keyboard, there may be a number of different keyboards defined. An application 
may enable any number of keyboards — as long as it keeps track of them. When a 
keyboard is no longer needed, you delete it either by using the QV_DELETE modifier 
with the QIO or by deassigning the associated channel. 

The following example shows a typical assignment of two terminal channels, 
keyboard requests on those channels, and the associated AST routines. (Appendix D 
of this manual shows this example in the context of a complete applications 
program.) 
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Example 2-1 Enabling Keyboard Requests 


P2.BL0CK2: 

.LONG 

.LONG 

.LONG 

.LONG 

ACK2: .ASCID 


P3_BL0CK: 


.LONG 

.LONG 

.LONG 

.LONG 


KBD^AST 

ACK2 

0 

CHARACTER 


AST specification block 2 
AST address 
AST parameter 
AST delivery mode 
input token 


/INPUT ACKNOWLEDGED CHANNEL 2/ ;AST parameter message 


CTL.AST 

0 

0 

0 


control AST specification 
block “ for both ASTs 
control AST address 
AST parameter 
AST delivery mode 
must be zero 


SET_KBDAST: 

$ASSIGN^S DEVNAM=WS_DEVNAM,- 
CHAN=KBD_CHAN2 

BLBS R0.20$ 

BRW ERROR 


assign channel using 
logical name and 
channel number 
no error if set 
error 


20 $: 


MOVL #IO$C_QV^ENAKB,RO 

$QI0W_S CHAN=KBD.ChAN2,- 

FUNC=#I0$^SETM0DE,- 

P1=(R0) 

P2=#P2_BL0CK2,- 
P3=#P3_BL0CK 
BLBS R0,30$ 

BRW ERROR 


enable keyboard AST 
request to RO 
assigned channel 
set mode QIO 
keyboard AST request 
user AST routine 
control AST routine 
no error if set 


(Continued on next page) 
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Example 2-1 (Cont.) Enabling Keyboard Requests 

KBD.AST: 

F5_AST: 



.WORD 




PUSHL 

4(AP) 

; send acknowledgment 


CALLS 

BLBS 

#1.G"LIB$PUT_LINE 

RO. 10$ 

: message 

5$: 

BRW 

ERROR 


10$; 

CMPW 

BNEQ 

#KEY$C_F5,CHARACTER 
20$ 

; was F5 typed? 


BSBW 

CYCLE_KBD 

; cycle the keyboard list 


BRB 

40$ 

; and exit 

20$: 

PUSHAL 

CALLS 

BLBC 

DESC 

#1,G*LIB$PUT_LINE 

R0.5$ 

; send character typed 


CMPB 

BNEQ 

#-A/C/,CHARACTER 

30$ 

; was a ”C” typed? 


BSBW 

BRB 

CYCLE.KBD 

40$ 

; cycle the keyboard list 

30$: 

CMPB 

BNEQ 

#*A/F/.CHARACTER 

40$ 

; was an "F" typed? 

40$: 

$SETEF_S EFN=#2 

RET 

; yes, exit program 


CTL^AST: 

.WORD 

PUSHAL 

CALLS 

BLBS 

5$: BRW 

CYCLE 

#1.G''LIB$PUT_LINE 
RO. 10$ 

ERROR 

; send acknowledgment 
; message 

10$: RET 




2.4.2 Keyboard Characteristics 

By default, keyboards have a set of characteristics associated with them. The default 
characteristics of a keyboard are defined by a data structure referred to as the system 
characteristics block. Appendix A illustrates this data structure and lists the keyboard 
characteristics and their defaults. 
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An application naay modify the default characteristics by specifying a system charac¬ 
teristics block as the fourth parameter of the Modify Systemwide Characteristics QIO. 
This block consists of four longwords: 

• The first longword contains a bit mask of the characteristics to enable. 

• The second longword contains a bit mask of the characteristics to disable. 

• The third longword is the key-click volume value in the range 1 to 8 (1 being 
loudest). 

• The fourth longword is the screen saver time, in minutes. 

To enable or disable default values, specify the predefined QVBDEF constant 
associated with each characteristic (also listed in the appendix) in the proper 
longword. If the key-click or screen saver characteristics are enabled, their respective 
values in the third and fourth longword are used. 

Once you have modified the systemwide defaults, any keyboard enabled without 
specifying keyboard characteristics takes the new default values. 

An application can also define the keyboard characteristics (auto repeat, key-click 
sound, function key transition) for a particular keyboard entry by specifying the 
address of a keyboard characteristics block as the fourth parameter of the Enable 
Keyboard Input QIO. This block also consists of four longwords: 

• The first longword contains a bit mask of the characteristics to enable. 

• The second longword contains a bit mask of the characteristics to disable. 

• The third longword is the key-click volume value in the range 1 to 8 (1 being 
loudest). 

• The fourth longword must be zero. 

The characteristics you can enable for a specific keyboard are the same as those 
for the systemwide defaults, except for the screen saver time — it is a systemwide 
characteristic (there is only one screen). See Appendix A. 

These characteristics are associated with the enabled keyboard. Whenever the 
keyboard is active, the physical keyboard will reflect these characteristics. To clarify, 
if an application enables two keyboards, one with autorepeat enabled and the other 
with autorepeat disabled; when the first keyboard is active any key held down will 
be sent repeatedly; when the other keyboard is active, the key will only be input 
once. 

To modify the characteristics of an existing keyboard, use the Modify Keyboard 
Characteristics QIO, specifying a keyboard characteristics block as the fourth 
parameter. Note that this QIO may also be used to change the keystroke AST 
and request AST associated with a keyboard. 
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2.4.3 Modifying the Keyboard Table 

The keys on the main keypad array of the physical keyboard are programmable. 
That is, an application may define the keys of the keyboard so that they are 
associated with any of the 255 characters in the multinational character set (including 
diacritical characters). (Appendix G contains a table showing the multinational 
character set.) An application may define several character sets to be accessed at 
different times by the same physical keyboard. 

You define a character set by constructing a data structure referred to as a keyboard 
table and then loading the new table using the Load Keyboard Table QIO. 

2.4.3.1 Constructing a Keyboard Table Using Macros 

You construct a keyboard table by initializing it with the default table values and 
then overriding any values you wish to modify. VWS provides macros to generate 
keyboard tables in SYS$LIBRARY:$QVBDEF.MLB. They are: 

• VC$KEYINIT — Initializes the table 

• VC$KEY — Loads individual key definitions 

• VC$KEYEND — Terminates the table 
These macros also appear in Appendix E. 

Initializing a Table 

To initialize a table, call VC$KEYINIT. This macro has one parameter, the address 
of the table, which it returns after allocating space and initializing the table. It is 
recommended that you specify this parameter and use the returned address when 
loading the table. By default, the system loads the North American keyboard table. 

Loading Key Definitions 

To load new key definitions, call VC$KEY. This macro has several parameters that 
permit you to define the various states of a given key. Note that you only need to 
modify the keys that are different from the default keys. Loading key definitions 
overrides the default definitions loaded by VC$KEYINIT. 

A key on the keyboard can have eight different states, depending on how the Shift, 
Control, and Lock keys are pressed in combination with the key. For each key, 
the keyboard table associates each state with a one-byte ASCII value representing 
a character from the multinational character set, so each key is described by a 
quadword in the table. The following table lists the states a key can have along with 
the byte within the quadword that describes each state. 
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Byte State 

1 Value of key 

2 Value of key if Shift key is also pressed 

3 Value of key if Control key is also pressed 

4 Value of key if both Shift and Control keys are also pressed 

5 Value of key if Lock is also pressed 

6 Value of key if both Lock and Shift keys are also pressed 

7 Value of key if both Lock and Control keys are also pressed 

8 Value of key if Lock, Shift, and Control keys are also pressed 

When you load a key using VC$KEY, you specify nine parameters, the ordinal key 
position, and the ASCII value associated with each of the eight states. 

Figure 2-1 shows the order of keys in the keyboard table. It illustrates the 
relationship of the physical key on the keyboard to the ordinal key position in 
the keyboard table (numerals in red). This particular table corresponds to the North 
American layout of characters on the keyboard. 

Figure 2-1 Keyboard Table Layout 



The following is an example of loading the tenth key of the keyboard table: 
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VC$KEY 10.- 

<*a/9/>.- 
<‘a/)/>.- 
<"xOFF>,” 
<^xOFF>,- 
<^a/9/>,- 
<^a/)/>.- 
<''xOFF>,- 
<^xOFF> 


ordinal key position 
key = 9 
Shift/key = ) 

Control/key = undefined 
Shift/Control/key = undefined 
Lock/key = 9 
Lock/Shift/key = ) 

Lock/Control/key = undefined 
Lock/Shift/Control/key = undefined 


Note that the hexadecimal value OFF is used to denote an undefined key (meaning 
no character is delivered). 


The following table shows the decimal values that should be used to represent 
diacritical characters. (Section 2.4.4 contains additional information on diacritical 
characters.) 


Diacritical Mark 

Equivalent Character 

Decimal Value 

Diaeresis (umlaut) 

A 

128 

Acute accent 


129 

Grave accent 


130 

Circumflex accent 

'' 

131 

Tilde 


132 

Ring 

o 

133 

(Reserved) 


134-159 


Terminating a Table 

To terminate a keyboard table, call VC$KEYEND. This macro has one parameter, 
the length of the table, which it returns. It is recommended that you specify this 
parameter and use the returned length when loading the table. 

The following example segment shows how the North American keyboard layout 
can be modified. (Appendix D of this manual shows this example in the context of a 
complete applications program.) 
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VC$KEYINIT KB_LAYOUT_TBL ; generate the new table 

: modify only the characters 
; specified 


VC$KEY 10. <“a/9/>. <'a/) />, <*xOFF>, <'‘xOFF>, - 
<''a/9/>. <“a/) />, <*xOFF>. <~xOFF> 

VC$KEY 11.<*a/0/>.<‘a/=/>.<*xOFF>,<'xOFF>,- 
<‘a/0/>.<“a/=/>,<*xOFF>,<*xOFF> 

VC$KEY 12,<"x081>.<''a/?/>,<''x0FF>,<*x0FF>,- ;diacritical (’) 
<*x081>. <'‘a/?/>, <*xOFF>, <'‘xOFF> 

VC$KEY 13,<'‘x082>,<''x083>,<*x01E>,<*x01E>,- ;diacriticals (‘ ~) 
<'‘X082>, <‘x083>, <*xOFF>, <*xOFF> 

VC$KEY 19.<'a/z/>,<*a/Z/>.<*x01A>,<*x01A>,- 
<~a./z/> , <*a/Z/>, <*x01A>, <'‘x01A> 

VC$KEY 24.<*xOE8>,<‘xOFC>,<*xOFF>.<*xOFF>,- 
<*xOE8>.<‘xOFC>,<“xOFF>,<"xOFF> 

VC$KEY 25.<*x080>.<‘x084>,<*x0FF>.<*x0FF>.- ;diacriticals (" ~) 
<‘x080>.<"x084>,<“xOFF>,<*xOFF> 


VC$KEYEND KB_LAYOUT_TBL_LEN ; end the table. 

; and determine its length 

2.4.3.2 Constructing a Keyboard Table Without Macros 

If you construct a keyboard table without using the provided macros, it must conform 
to the structure shown in Figure 2-2. 
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Figure 2-2 Keyboard Table Description 


31 0 



version number 


char 4 

char 3 

char 2 

char 1 

char 8 

char 7 

char 6 

char 5 


ZK-5347-86 


• The first quadword of the table must contain the version number for the table. 
Typically this value will be 1. 

• Each subsequent quadword describes the eight states of a key in the main array 
of the keyboard, in the order shown in Figure 2-1. 

• Every key must be defined. 

2.4.3.3 Loading a Keyboard Table 

To load a keyboard table, use the Load Keyboard Table QIO, specifying the address 
and size of the table and the channel of the keyboard entry with which you 
wish to associate the table. Note that the address and length are returned by the 
VC$KEYINIT and VC$KEYEND macros, respectively. 

Once a keyboard table is loaded and the associated keyboard becomes active, the 
physical keyboard reflects the definitions in the table. 

You can also revert to the default keyboard table by calling the Revert to Default 
Keyboard Table QIO. This QIO also returns the space used by a private table (if one 
was loaded) to pool. 

The following example shows a typical routine for loading a keyboard table. 
(Appendix D of this manual shows this example in the context of a complete 
applications program.) 
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SET_FRENCH_KB: 
MOVL 
$QI0W_S 


BLBS 

BRW 

5$: RSB 


2.4.4 Composing Nonstandard Characters 

Compose sequences permit you to define combinations of keys to represent 
multinational characters not already defined as standard keys in the keyboard 
table. 

There are two types of compose sequences: two-stroke sequences and three-stroke 
sequences. Three-stroke sequences can be used on all keyboards. To perform a 
three-stroke sequence, you press the Compose key and then press two standard keys. 
Two-stroke sequences can be used on all keyboards except the North American 
keyboard. To perform a two-stroke sequence, you press a diacritical mark and then 
press a standard key. 

A diacritical mark is one of the following nonspacing characters: 

grave accent 
acute accent 
circumflex accent 
tilde 

diaeresis (umlaut) 
ring 

Diacritical marks are available on all but the North American keyboard. (This is 
why two-stroke sequences are not possible on the North American keyboard.) 

The diacritical marks vary among the keyboards according to the relative usage 
of characters with diacritical marks. Users should note that only one of several 
characters shown on a key cap may be a diacritical mark; some keyboards have keys 
that contain both a standard character and a diacritical mark. 


#<IO$C^QV^LOAD^KEY_TABLE>, RO 
CHAN = KBD.CHANl, - 
FUNC = #I0$^SETM0DE, - 
PI = (RO). - 
P2 = #KB^LAYOUT.TBL_LEN, 

P3 = #KB^LAYOUT^TBL 

R0.5$ 

ERROR 


change the keyboard 
layout 

keyboard table size 
keyboard table 
address 

no error if set 




How to Program to the Driver 2-i5 


You define compose sequences by constructing a data structure referred to as a 
compose sequence table (either two-stroke, three-stroke, or both) and then loading 
the table with the Load Compose Sequence Table QIO. 

2.4.5 Constructing Compose Sequence Tables 

A compose sequence table lists a series of compose sequences. The structures of a 
three-stroke table and a two-stroke table differ slightly. 

Three-Stroke Compose Sequence Table Structure 

Three-Stroke compose tables have three parts: 

1. The first part of the table is a longword containing the version number for the 
table. (Typically this value will be 1.) 

2. The second part of the table is a series of longwords, each of which describes 
a compose sequence. These longwords list the two standard keys used in the 
compose sequence and hold an address that points to the associated output 
string. They have the format shown in Figure 2-3. 

Figure 2-3 Three-Stroke Compose Sequence Table Description 

_3 + 2_1_q Byte 


address of output string 

char 2 

char 1 

(output) 

(input) 

(input) 


ZK-4451-85 


3. The third part of the table is the counted string that bytes 2 and 3 of the 
longword (address of output string) point to. All the counted strings must 
be grouped together, and must follow the list of longwords that describe the 
compose sequences. 

Figure 2-4 shows the structure of an entire three-stroke compose sequence table. 
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Figure 2-4 Three-Stroke Compose Sequence Table 

31 0 


version 

number 


address of output string 

char 2 

char 1 

(output) 

(input) 

(input) 


(list of longword descriptions) 


counted strings 



ZK-4452-85 


Two-Stroke Compose Sequence Table Structure 

Two-Stroke compose sequence tables have four parts: 

1. The first part of the table is a longword containing the version number for the 
table. (Typically this value will be 1.) 

2. The second part of the table is a 32-byte diacritical table. This table defines 
which characters are diacriticals. Each bit in the diacritical table corresponds to 
the equivalent ASCII character code in the multinational character set. If a bit is 
set in this table, the corresponding character is considered a diacritical character. 
Note that this means it is possible to define nonstandard diacritical characters. 
For example, if bit 65 (decimal) were set, then the uppercase letter "A" would be 
a diacritical character. If bit 112(decimal) were set, then the lowercase letter "p" 
v/ould be a diacritical character. 

In order to support standard diacritical characters, represent the characters using 
the decimal values shown in the following table. 
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Diacritical Mark 

Equivalent Character 

Decimal Value 

Diaeresis (umlaut) 

A 

128 

Acute accent 


129 

Grave accent 


130 

Circumflex accent 


131 

Tilde 

- 

132 

Ring 

o 

133 

(Reserved) 


134-159 


3. The third part of the table is a series of longwords, each of which describes a 
compose sequence. These longwords list the diacritical key and the standard key 
used in the compose sequence and hold an address that points to the associated 
output string. They have the format shown in Figure 2-5. 

Figure 2-5 Two-Stroke Compose Sequence Table Description 

_3 I 2_1_q Byte 


address of output string 

char 2 

char 1 

(output) 

(input) 

(input) 
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The list of longwords in the table must be in ascending order by ASCII collating 
sequence using both input characters, as shown in the following example. 


Incorrect Table 

Correct Table 

s s 1 6 

AEIJE 

AEl JE 

A - 1 A 

"ala 

"ala 

A - 1 A 

s s 1 6 


4. The fourth part of the table is the series of counted strings that bytes 2 and 3 of 
each longword (address of output string) point to. All the counted strings must 
be grouped together, and must follow the list of longwords that describe the 
compose sequences. 

Figure 2-6 shows the structure of an entire two-stroke compose sequence table. 




2-18 How to Program to the Driver 


Figure 2-6 Two-Stroke Compose Sequence Table 


31 


version number 

L diacritical table 

:i 

(32 bytes) 


address of output string 

char 2 

char 1 

(output) 

(input) 

(input) 

(list of longword descriptions) 


L 




» 


counted strings 


i 



r 
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2.4.5.1 Constructing Compose Sequence Tables Using Macros 

You construct a compose table by initializing it and then loading the sequences 

you wish to define. VWS provides macros to generate compose tables in 

SYS$LIBRARY:$VWSSYSDEF.MLB. They are 

• VC$COMPOSE_JCEYINIT — Initializes the table 

• VC$COMPOSE_KEY — Loads individual sequence definitions 

• VC$COMPOSE_KEYEND — Terminates the table 

These macros also appear in Appendix F. 

Initializing a Table 

To initialize a table, call VC$COMPOSE_KEYINIT. This macro has two parameters: 

• The address of the table, which it returns after allocating space and initializing 
the table. It is recommended that you specify this parameter and use the 
returned address when loading the table. 

• The Compose—2 flag, which, if set equal to YES indicates that a two-stroke 
sequence table should be built. If the flag is not set, a three-stroke table is built. 
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Loading a Compose Sequence 

To load a compose sequence, call VC$COMPOSE_KEY. This macro has four 
parameters that permit you to define the two input characters (either the two 
standard keys for a three-stroke sequence or the diacritical and standard key for a 
two-stroke sequence), the output string, and the output string length. The following 
is an example of loading a three-stroke compose sequence: 


VC$C0MP0SE_KEY <'‘a/A/>, - 


<"xc4> 


input A 
input " 

default output length 
output character 


Terminating a Table 

To terminate a keyboard table, call VC$COMPOSE-JKEYEND. This macro has one 
parameter, the length of the table, which it returns. Typically, you specify this 
parameter and use the returned length when loading the table. 

2.4.5.2 Loading a Compose Table 

To load a compose table, use the Load Compose Table QIO, specifying the address 
and size of the table and the channel of the keyboard entry with which you 
wish to associate the table. Note that the address and length are returned by the 
VC$COMPOSE_KEYINIT and VC$COMPOSE_KEYEND macros, respectively. 

The Micro VMS Workstation is shipped with c^r'.es of the DIGITAL standard three- 
stroke and two-stroke compose tables residing within the driver. These are the 
default tables until alternate default tables are loaded. Note that DIGITAL standard 
two-stroke compose sequences are not supported on the North American keyboard. 

You can also revert to the default compose table by calling the Revert to Default 
Compose Table QIO. 

The following example shows how to load a three-stroke compose table. 
(Appendix D of this manual shows this example in the context of a complete 
applications program.) 
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SET_C0MP0SE3_TABLE: 

MOVL #<I0$C_QV_L0AD_C0MP0SE_TABLE>, RO 
$QI0W_S CHAN = KBD^CHANl, - ; change the compose table 

FUNC = #I0$^SETM0DE, - 
PI = (RO), - 

P4 = #C0MP0SE3_TBL_LEN, - ; three-stroke table size 
P5 = #C0MP0SE3_TBL ; three-stroke table addr 

R0,5$ ; not set on error 

ERROR 


5$: 


BLBS 

BRW 

RSB 


VC$C0MP0SE_KEYINIT C0MP0SE3^TBL 


generate an 
empty table 
fill the table here 


VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE^KEY 

VC$C0MP0SE^KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE^KEY 


<^a/A/>,<^a/'7>,,<"xc4> 

<^a/A/>,<^a/V>. ,<''xcl> 

<"a/A/>,<"a/*/>,,<"xc5> 
<^a/A/>,<^a/A/>,<@> 

<"a/A/>,<"a/E/>,,<"xc6> ; order sensitive 
<"a/A/>,<"a/"/>.,<"xc2> 

<"a/A/>,<"a/_/>,,<"xaa> 


VC$C0MP0SE.KEYEND C0MP0SE3_TBL^LEN ; end the table 

; and determine its 
; length 


2.5 Using a Pointer Device 

The drivers are designed to detect two pointer-related conditions: 

• Pointer movement 

• Pointer button transition 

The QIO interface permits you to associate regions of the screen with action ASTs 
that the driver fires whenever it detects pointer movement or a pointer button 
transition (clicking up or down). The action ASTs are application dependent and 
permit you to perform such screen manipulation as highlighting a menu when the 
pointer moves into it, or performing an action once a menu item is selected. 
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As described in Chapter 1, the driver uses separate lists to keep track of pointer 
movement and button transitions. The following sections describe how to create list 
entries for pointer movement and button transitions. 

Creating a Pointer Movement Entry 

To create a pointer movement entry, use the Enable Pointer Movement QIO. When 
you create a pointer movement entry, you may specify: 

• The address of a four-longword AST specification block. The four longwords 
contain 

1. The address of an AST routine that determines what action to take when 
movement is detected within the specified region. 

2. An optional user-defined AST parameter that is delivered to the AST. 

3. Access mode at which to deliver the AST (maximized with the current access 
mode). 

4. The address of a longword at which the driver stores the new cursor position, 
so that it is accessible to the application. 

The low-order word of the longword holds the X pixel position and ranges 
from 0 to 1023, where 0 is the left side of the screen. The high-order word 
holds the Y pixel position and ranges from 0 to 863, where 0 is the bottom 
of the screen. 

• The address of an AST routine that is invoked whenever the pointer exits the 
specified region. Typically, this AST performs any necessary cleanup actions, for 
example, turning off a region highlighted by the action AST. 

• Address of a screen rectangle values block that describes the region to be 
associated with the ASTs. 

By default, an entry is placed at the top of the list. However, an application may 
determine the position of the entry in the list by specifying optional modifiers to the 
QIO. The modifiers can be used to: 

• Place the entry last on the list (Q\L.LAST) 

• Delete the entry (QV-DELETE) 

Whenever you move the pointer (mouse, stylus, or puck), the driver checks the 
pointer position against the region descriptors of the pointer movement list entries. 
When the driver finds an entry whose region descriptor includes the current pointer 
position, the driver fires the action AST associated with that entry. 

If you specified an exit AST, the driver fires that AST when it detects that the pointer 
position is no longer within the specified region. 

If two regions overlap, the first one on the list gets the AST. 
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The following example shows how a pointer motion AST could be programmed. 
(Appendix D of this manual shows this example in the context of a complete 
applications program.) 


10$: MOVL #I0$C_QV_M0USEM0V,R0 • 

$QI0W_S CHAN=MOUSE_CHAN,- 

FUNC=#I0$_SETM0DE.- 

P1=(R0) 

P2=#M0USE_BL0CK.- 
P6=#M0USE_REGI0N 
BUBS R0.20$ 

BRW ERROR 

20$: RSB 


enable pointer motion 
channel 

QIO function code 
driver function code 
associated AST block 
associated region 
no error if set 


MOUSE.BLOCK: 

.LONG MOUSE^AST 
.LONG M0USE_ACK 
.LONG 0 
.LONG M0USE_XY 


pointer region AST 
specification block 
AST address 
AST parameter 
access mode 

new pointer cursor position 
storage 


M0USE_REGI0N: 

.LONG 400 
.LONG 400 
.LONG 800 
.LONG 800 


pointer region 
lower left corner 

upper right corner 


Creating a Pointer Button Transition Entry 

To create a pointer button transition entry, use the Enable Button Transition QIO. 
When you create a button transition entry, you may specify: 

• The address of a four-longword AST specification block. The four longwords 
contain 

1. The address of an AST routine that determines what action to take when a 
transition is detected within the specified region. 

If no AST routine is specified, input (the button transition) will be stored in 
the typeahead buffer, and delivered either when an AST region is declared 
using the same channel or when a Get Next Input Token QIO is issued using 
the same channel. 
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2. An optional user-defined AST parameter that is delivered to the AST. 

3. Access mode at which to deliver the AST (maximized with the current access 
mode). 

4. The address of a longword at which the driver stores the button transition 
value (token) when the AST service routine is called. 

Your application uses this longword to determine which pointer button 
has undergone a transition. The button transition value (the token) is a 
decimal value indicating which button was activated; the transition values 
are 400, 401, 402, and 403. The values are assigned to the pointer buttons 
sequentially starting with the select button, which is always 400. The driver 
stores the token in the low-order word of the longword. Bit 15 of the high- 
order longword determines whether the transition is up or down; 

1 equals down, 0 equals up. 

The rest of the high-order word contains more control information that 
can be used to determine if the Shift, Control, or Lock keys are depressed. 
You can use these keys as meta-keys (keys used in combination). Bit 14 
corresponds to the Shift key, bit 13 corresponds to the Control key, and bit 
12 corresponds to the Lock key. When the bit is set, the key is down. 

• The address of a pointer button characteristics block which determines whether 
delivery of subsequent transitions depends on all the buttons being in the up 
position. By default, the specified button transition AST gets all transitions until 
all buttons are returned to the up position. (See the description of this data 
structure in Appendix A.) 

• Address of a screen rectangle values block that describes the region to be 
associated with the button transition AST. 

By default, an entry is placed at the top of the list. However, an application may 
determine the position of the entry in the list by specifying optional modifiers to the 
QIO. The modifiers can be used to: 

• Place the entry last on the list (QV_LAST) 

• Delete the entry (QV_DELETE) 

• Purge the typeahead buffer (QV_PURG_TAH) 

If a button changes state (is clicked up or down), the driver checks the pointer 
position against the region descriptors of the button list entries. When the driver 
finds a region descriptor which contains the current pointer position, it fires the 
associated button transition AST. 

If two regions overlap the first one on the list gets the AST. 
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The following example shows the typical programming and use of pointer button 
ASTs. (Appendix D of this manual shows this example in the context of a complete 
applications program.) 


SET.BUTTONAST: 

$ASSIGN_S DEVNAM=WS^DEVNAM,- 
CHAN=BUT.CHAN 

BLBS R0,10$ 

BRW ERROR 


assign channel using 
logical name and 
channel number 
no error if set 
error 


10$: MOVL #I0$C_QV_ENABUTT0N,RO 

$QI0W.S CHAN=BUT_CHAN,- 

FUNC=#I0$_SETM0DE,- 
P1=(R0).~ 
P2=#BUT_BL0CK,- 
P6=#BUT_REGI0N 
BLBS R0,20$ 

BRW ERROR 

20$: RSB 

BUT.BLOCK: 

.LONG BUT.AST 
.LONG 0 
.LONG 0 
.LONG BUTTON 


enable button trans. 
channel 

QIO function code 
driver function code 
associated AST block 
associated region 
no error if set 


button transition AST 
specification block 
AST address 
AST parameter 
access mode 
button information 
longword 


BUT.REGION: 

.LONG 20 
.LONG 20 
.LONG 300 
.LONG 300 


associated region 
lower left corner 

upper right corner 
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2.6 Using the Typeahead Buffer 

In the case of keyboard input, pointer movement, and button transitions, the driver 
accepts three kinds of input: character input, pointer position, or button transition 
value. Often input is received faster than an application can (or chooses to) process 
it. When this happens the character and button information is stored in the typeahead 
buffer. (Pointer movement inputs the new pointer position, but if the input cannot be 
delivered, it is ignored, not buffered.) 

The typeahead buffer is part of each entry on the list. It is 128 bytes long, so you are 
able to buffer 32 input tokens (each token is four bytes long). 

2.6.1 Getting Input from the Typeahead Buffer 

You can get input from the typeahead buffer in two ways: 

• Associate a repeating AST with the entry when it is enabled to continuously 
process buffered input. (In the case of keyboards, you may also associate a 
repeating AST when you modify the keyboard.) 

• Issue a Get Next Input Token QIO to process a single input token from the 
buffer (this QIO may optionally have an AST associated with it — the input is 
delivered in the lOSB block in either case). This type of single-token processing 
is referred to as a "one shot". 

Once a repeating AST is associated with an entry, any attempt to issue subsequent 
one shots on that entry will return an error because the results are unpredictable. If 
you enable an entry without an associated AST you can issue one shots to process 
the buffered data one character at a time. You can associate a repeating AST with 
an entry at any time, by reenabling the entry (or for keyboards, modifying the 
keyboard). However, any outstanding one shots will be processed first. 

Note that QIO modifiers permit you to purge the typeahead buffer. If you delete 
an entry, and the typeahead buffer is not empty, the deletion is deferred until the 
typeahead buffer is empty. If an application wants to immediately delete an entry, it 
must first purge the buffer. 
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2.7 Intercepting Input 

As noted above, you can issue one shots on a channel that currently has no 
repeating AST associated with it. To "intercept" input, disable the associated AST (by 
reenabling the entry without the AST specification) and then issue one shots. (Note 
that for a keyboard you can disable an AST by modifying the keyboard instead of 
reenabling it.) At a later point you may reenable the repeating AST. 

To intercept the input for an entry on a list, issue the Get Next Input Token QIO 
specifying the type of input token (IO$C^QV-_ENAKB, IO$C_Q\LMOUSEMOV, or 
IO$C_ENABUTTON), and the channel with which the entry is associated. 

One shots are also useful when you wish to process input from within an AST (ASTs 
cannot be delivered in this case). An application can rely on the fact that a one shot 
with no associated AST will deliver the input to the lOSB. By using an event flag and 
the lOSB, the application can process the typeahead buffer one character at a time 
from within the AST. 

The example in Appendix D contains instances of intercepting input. 


2.8 Defining Cursor Patterns 

The QIO interface also permits you to associate a region of the screen with a specific 
cursor pattern. Using this feature, you may change the shape and size of the cursor 
to reflect a change in functionality; for example, an editing cursor may take one 
shape while a menu selection cursor takes another. Again, the driver maintains an 
entry list to keep track of cursor patterns. 

To create a cursor pattern entry, use the Define Pointer Cursor Pattern QIO. When 
you create a cursor pattern entry, you may specify: 

• The address of a bitmap image for the new cursor pattern. This is either a 
16-word array or, on multiplane cursor systems, a 32-word array. The QVB 
contains a field that determines whether you have a one- or multiplane system, 
use the Get System Information QIO to access this field. The following section 
describes multiplane cursor patterns. 

• The address of a longword to contain a new cursor position. This optional 
parameter permits you to reposition the cursor. 

• The address of the cursor hot spot definition. The hot spot is the one position 
within the bitmap image of the cursor that is the actual cursor position. 

• Cursor style. This value defines how the cursor appears against the background 
of the screen. (It is ignored on multiplane cursor systems.) 
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• Address of a screen rectangle values block that describes the region to be 
associated with the cursor pattern. 

By default, an entry is placed at the top of the list. However, an application may 
determine the position of the entry in the list by specifying optional modifiers to the 
QIO. The modifiers can be used to 

• Place the entry last on the list (QV—LAST) 

• Delete the entry (QV_DELETE) 

As the pointer is moved, the driver checks the pointer position against the region 
descriptors of the cursor pattern list entries. When the driver finds a region descriptor 
which contains the current pointer position, it changes the cursor pattern to the one 
associated with the region. 

The following example shows the typical assignment of a single-plane cursor region 
pattern. (Appendix D of this manual shows this example in the context of a complete 
applications program.) 


QV$CURS0R1: 

.WORD 

.WORD 

.WORD 

.WORD 

.WORD 

.WORD ^bllllllllllllllll 
.WORD 

.WORD ^bllllllllllllllll 

.WORD 

.WORD 

.WORD 

.WORD 

.WORD 

.WORD 

.WORD 

.WORD ^bllllllllllllllll 


initial 16 x 16 cursor 
"solid” pattern 
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REGIONl: 


20 $: 




cursor region 1 

.LONG 

20 

lower left corner 

.LONG 

20 


.LONG 

300 

upper right corner 

.LONG 

300 


MOVL 

#IO$C_QV^SETCURSOR,RO 

define cursor 1 

$QI0W_S 

CHAN=CUR_CHAN1,- 

channel 


FUNC=#I0$_SETM0DE,- 

QIO function code 


P1 =(R0).- 

driver function code 


P2=#QV$CURS0R1.- 

cursor pattern 


P6=#REGI0N1 

associated region 

BLBS 

R0,30$ 

no error if set 

BRW 

ERROR 



2.8.1 Multiplane Cursor Patterns 

If your system uses a multiplane cursor, you may specify a 32-word array as a cursor 
pattern. Currently, multiplane cursors consist of two planes. Typically, you use 
two planes to prevent the cursor from disappearing when it is moved over varying 
backgrounds. To understand how the two planes work think of the 32-bit array as 
two 16-word arrays, array A and array B. 

The bit pattern in array A is determined in the following way. 

• A 1 in a bit indicates that the corresponding pixel be filled. 

• A 0 in a bit indicates that whatever is on the screen at the corresponding pixel 
should show through (remember, the cursor is overlaid on the screen). 

The bit pattern in array B uses the bits set to 0 in array A as a mask: those 
corresponding bits are ignored in array B. The remaining bit pattern in array B is 
determined in the following way: 

• A 1 in a bit indicates that the corresponding pixel be filled with the background 
color. 

• A 0 in a bit indicates that the corresponding pixel be filled with the foreground 
color. 
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2.9 Using an Alternate Windowing System 

To provide greater jflexibility the QVSS driver supports a single private graphics 
application in addition to the default, VWS-supplied, windowing package. That is, 
you can write an alternate windowing application that takes complete control of 
video memory and does not depend on VWS-supplied window or graphics services. 

To enable alternate windowing take the following step: 

1. Modify the command procedure SYSTARTUP.COM to define the logical 
name UIS$WS_ALTAPPL to "TRUE". This definition must occur before the 
STARTVWS.COM command procedure is invoked. 

This instructs the driver to reserve one-half of video memory for a private 
application. When requested by the private application this part of video memory is 
mapped to the screen and made available to the application. All set mode functions 
issued by the application relate only to its private video memory. A user interface 
key (F3) on the keyboard allows an operator to switch between windowing systems 
dynamically. 

Note that private applications are device dependent and that only one private 
application may be active at a time. 


2.10 Drawing to the QVSS Screen 

To draw to the screen using the QVSS driver, take the following steps: 

1. Access the QVB. 

2. Manipulate bits in video memory. 

3. Map the manipulated video memory to the screen. 

Section 2.2 describes how to access the QVB. The following sections describe how to 
manipulate bits and map video memory to the screen. 

2.10.1 Manipulating Bits in Video Memory 

A QVSS application "draws" by directly setting bits in video memory. To access 
video memory use the QVB$L_MAIN-_VIDEOADDR address in the QVB. It is the 
responsibility of the application to determine how to offset into video memory. 
When manipulating memory, keep the following in mind: 

• Each scanline of video memory is 1024 bits (128 bytes) wide. 

• There are 1024 scanlines in memory. (Note that if an alternate windowing 
system is used, the accessible number of scanlines is effectively halved.) 
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2.10.2 Mapping Video Memory to the Screen 

To map a scanline in memory to the screen, you must load an entry in the scanline 
map. The scanline map consists of word-length entries whose positions in the map 
correspond to line positions on the screen and whose contents are indexes of scanline 
positions in video memory. The index of scanlines in memory starts at zero and is 
simply incremented by one for each scanline. 

Mapping with an Alternate Windowing System 

This scheme is straightforward unless you are using an alternate windowing system, 
in which case memory is split in half and shared by two systems. You must ensure 
that you are mapping the correct portion of memory by calculating the correct 
scanline base in video memory. To obtain the correct scanline base, do the following: 

1. Subtract the QVB_$L_VIDEOADDR address from the QVB$L_MAIN_ 
VIDEOADDR address. 

2. Divide the result by 128 (number of bytes in a scanline). 

Add the base to any scanline index before inserting it as an entry in the scanline 
map. 


2.11 Creating a QDSS Viewport 

The QDSS driver performs all operations to the screen using viewports. If your 
application is not using the UIS windowing interface, it must either create a viewport 
before attempting to write to the screen, or use the systemwide viewport (the entire 
screen). Example 2-5 demonstrates how to access the systemwide viewport. 

To create a viewport an application must perform the following steps: 

1. Assign the viewport a channel. 

2. Get a viewport ID. 

3. Define the location and size of the viewport. 

4. Start the viewport. 

The following sections describe how to perform each of these steps. 

2.11.1 Assigning a Viewport Channel 

To obtain a unique channel for a viewport, use the $ASSIGN system routine. The 
actual association of the viewport with the channel occurs when the application gets 
a viewport ID for the viewport. 
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2.11.2 Getting a Viewport ID 

To get a viewport ID, use the Get Viewport ID QIO. One parameter of this QIO 
specifies the address of the longword to receive the ID. The ID stored at that address 
is used to identify which viewport is the object of all subsequent operations. The 
channel the application specifies in this QIO is associated with the viewport. 


2.11.3 Defining a Viewport 

As described in Chapter 1, a viewport is defined by one or a number of rectangular 
update regions. Update regions are defined in buffers known as Update Region 
Definition (URD) buffers. Each URD buffer contains coordinate information that 
defines the dimensions, in pixels, of a rectangle, and its location relative to the 
base of QDSS memory either onscreen or offscreen. (See Appendix B for detailed 
information about this data structure.) A viewport may be defined by one or more 
URDs. Figure 2-7 illustrates a 500- by 500-pixel viewport defined by a single URD 
and displays the contents of the associated definition buffer. 

Figure 2-7 Viewport and Update Region Definition Buffer 
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Note that the base is given in absolute coordinates while the two defining corners of 
the viewport are given in viewport relative coordinates. This becomes important 
when a viewport is divided into a number of rectangles and some (occluded) 
rectangles are stored in offscreen memory. Drawing operations use the relative 
coordinates to perform drawing even when rectangles are not visible on the screen. 

To define a viewport: 

• Allocate and initialize one or more URD buffers that describe the viewport's size 
and relative position. 

• Call the Define Viewport Region QIO once for each viewport, passing the URD 
(or array of URDs if the viewport is more than one rectangle). 
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Parameters of the Define Viewport Region QIO specify the address of the viewport 
definition buffer, the length of that buffer, and the viewport ID. 

You can redefine a viewport at any time by reinvoking the Define Viewport Region 
QIO with new coordinate information and the same channel and viewport ID. 

2.11.4 Starting the Viewport 

When you define a viewport, it is in a "stopped" state. To permit operations to the 
viewport, you must explicitly start the viewport request queue. To start the viewport 
request queue, use the Start Request Queue QIO. 

The following example creates and starts a viewport that is 100 pixels square, and 
has its lower left comer at the absolute device coordinate (10,10). Note that in 
FORTRAN you must include the lODEF library in order to access the QIO function 
codes. 
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Example 2-2 Creating a Viewport 

PROGRAM CREATE_VIEWPORT 
IMPLICIT INTEGER*4(A-Z) 

INCLUDE ’VWSSYSDEF’ 

INCLUDE ’($I0DEF)’ 

INTEGER*2 CHAN.VPl, 

2 CHAN_VP2 

! Declare URDs 
INTEGER*2 URD1_VP1(6). 

2 URD1_VP2(6) 

! Load URDl.VPl buffer 

URD1_VP1(1) = 0 ! lower left corner 

URD1_VP1(2) = 0 

URD1_VP1(3) = 99 ! upper right corner 

URD1_VP1(4) = 99 

URD1_VP1(5) = 10 ! absolute coordinate base 

URD1_VP1(6) = 10 

! define and start VPl 

CALL VIEWPORT (URD1_VP1, CHAN.VPl, VP1_ID) 


! Viewport Subroutine 

SUBROUTINE VIEWPORT (VP_URD, VP_CHANNEL. VIEWPORT.ID) 

IMPLICIT INTEGER*4(A-Z) 

INCLUDE *VWSSYSDEF’ 

INCLUDE ’($I0DEF)’ 

INTEGER*2 VP^CHANNEL 

! Obtain a channel for the viewport 
CALL SYS$ASSIGN (’SYS$WORKSTATION^ 

2 VP.CHANNEL,,) 


! device name 
! channel 

(Continued on next page) 
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Example 2-2 (Cont.) Creating a Viewport 


! Get a viewport ID 
CODE = I0$_SENSEM0DE 
STATUS = SYS$QI0W (. 

2 y,VAL(VP_CHANNEL), ! 

2 7.VAL(C0DE), ! 

2 

2 ’/.VALdOSC.QD.GET.VIEWPORT.ID), 

2 VIEWPORT_ID, ! 

2 ’/.VALCA), ! 

2 . ,) 

IF (STATUS .NE. 1) THEN 

CALL LIB$SIGNAL ('/.VAL (STATUS)) 

END IF 


channel 

QIO function code 


address of ID buffer 
VP ID buffer length 


! Define the Viewport Region 
CODE = I0$_SETM0DE 
STATUS = SYS$QI0W (, 

2 7,VAL(VP_CHANNEL). ! channel 

2 y.VAL(C0DE),' ! QIO function code 

2 

2 y,VAL(IO$C_QD_SET_VIEWPORT_REGIONS), 

2 VP_URD, ! address of URD buffer 

2 y,VAL(URD$C_LENGTH), ! length of URD buffer 

2 y.VAL(VIEWPORT_ID). ,) ! address of VP ID 

IF (STATUS .NE. 1) THEN 

CALL LIB$SIGNAL C/.VAL (STATUS)) 

END IF 


! Start the Viewport 
STATUS = SYS$QI0W (, 
2 
2 
2 
2 
2 
2 

IF 


y.VAL(VP_CHANNEL) , 
y.VAL(C0DE) . 

y.VAL(IO$C_QD_START) , 
y.VAL(VIEWPORT_ID) , 

1) THEN 


(STATUS .NE. 

CALL LIB$SIGNAL (%VAL (STATUS)) 
END IF 


! channel 

! QIO function code 

! QD function code 
! address of ID buffer 


RETURN 

END 
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2.12 Drawing with the QDSS Driver 

Unlike the QVSS driver, the QDSS driver has drawing capabilities. The QDSS driver 
uses data structures known as drawing operation primitives (DOPs) to perform 
drawing operations. Your application loads a DOP with all the information necessary 
for the hardware to perform a drawing operation. Typically, a DOP contains the type 
of operation to perform (that is, draw a line, draw text, and so on), the number of 
times to perform it, and any coordinates needed to perform the operation. 

As described in Chapter 1, you must allocate storage for DOPs, insert DOPs on the 
request queue to execute them, and reuse the storage using the return queue. If your 
application is using the UIS windowing environment, you can perform all three of 
these functions using the UISDC routines. However, if your application is not using 
the UIS windowing environment, the application must manage DOP storage and 
insert DOPs on the request queue. 

Chapter 5 describes how to perform drawing using DOPs. It describes: 

• The structure of DOPs 

• How to use the UISDC interface 

• How to allocate and execute DOPs without the UISDC interface 


2.13 Using Bitmaps 

Although the QDSS driver does not support direct manipulation of the onscreen 
bitmap, it does permit you to copy bitmap images from processor memory to 
onscreen and offscreen memory and from on and offscreen memory to processor 
memory. 

The driver provides the following QIOs for manipulating bitmaps: 

Write Bitmap — Copies a bitmap from processor memory to QDSS screen memory 
and performs bitmap-to-bitmap transfers (onscreen-to-offscreen and offscreen-to- 
onscreen). 

Read Bitmap — Copies a bitmap from QDSS memory to processor memory and 
performs bitmap-to-bitmap transfers (onscreen-to-offscreen and offscreen-to- 
onscreen). 

Load Bitmap — Loads a bitmap to be used by a text or fill pattern drawing operation 
from processor memory into the reserved bitmap area of offscreen memory (see 
Figure 1-4). This QIO returns a bitmap ID that the DOPs use to reference the 
bitmap. Bitmaps loaded by this QIO must follow certain criteria; see the QDSS QIO 
section for details. The UISDC interface also provides a Load Bitmap function. (See 
Chapter 5.) 
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To draw an image, build it in processor memory, then load it into QDSS memory 
using the Write Bitmap QIO. 

To store an image in processor memory, copy the bitmap from QDSS memory to 
processor memory, using the Read Bitmap QIO. (This is what is done for occluded 
viewport regions when offscreen memory becomes full; see Section 2.18.) 

To load a bitmap for use with a DOP, use the Load Bitmap QIO. 

Example 2-3 illustrates the use of the Write Bitmap QIO to copy a region from 
onscreen memory into offscreen memory (a bitmap-to-bitmap transfer). 


2.14 Synchronizing Viewport Activity 

Because of the asynchronous way DOPs are queued for processing and execution, 
you must take special actions if you wish to synchronize activity on a viewport. 

Figure 2-8 illustrates the three states that DOPs may have. They may be: 

• In the queue, waiting to be processed 

• Currently being processed by the driver 

• Completed and on the screen 


Figure 2-8 Synchronizing Viewport Activity 

In Queue Processed by 

Driver 


On the Screen 



At any given time, the driver may be processing a number of DOPs. To synchronize 
activity, you must manipulate the queue and be aware of whether the driver is 
currently processing DOPs. 
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QIOs 

The QIO interface provides the following QIOs to use for synchronization: 

Stop Request Queue — Immediately halts the processing of the request queue and 
waits for whatever is currently being processed to complete before returning. 

Start Request Queue — Restarts processing on a stopped request queue. 

Suspend Request Queue — Immediately halts the processing of the request queue but 
does not wait for whatever is currently being processed to complete before returning. 

Resume Request Queue — Resumes processing on a suspended request queue. 

Hold Viewport Activity — Does not permit any viewport except the systemwide 
viewport to write to the screen (processing actually continues.) 

Release Hold — Releases the hold on viewport activity. 

Insert DOP — Permits an application to insert a DOP on the request queue and waits 
for completion — essentially performing a synchronous DOP. 

DOPs 

In addition to these QIOs, the request queue interface permits you to submit the 
following DOPs: 

Stop Viewport Activity — Halts the queue and waits for any DOPs currently 
processing to complete. This differs from the Stop Request Queue QIO in that 
all DOPs inserted before this one are guaranteed to execute before the queue is 
stopped. 

Start Viewport Activity — Restarts processing on a stopped request queue. 

Suspend Viewport Activity — Halts the queue but does not wait for any DOPs currently 
processing to complete. This differs from the Suspend Viewport Activity QIO in that 
all DOPs inserted before this one are guaranteed to execute before the queue is 
stopped. 

Resume Viewport Activity — Resumes processing on a suspended request queue. 

A Stop also differs from a Suspend in that a Stop issued on a stopped request 
queue waits for the queue to restart, then takes effect — while a Suspend issued 
on a suspended viewport is ignored. This makes the Stop useful for synchronizing 
multiprocess windowing activity on a single viewport. A process can guarantee that 
no other process is accessing the viewport by issuing a Stop before attempting any 
windowing activity (redefining URDs, and so forth). When control returns from the 
Stop, the process knows that no other process' DOPs can execute on the viewport 
and any DOPs that were processing have completed. 
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Note that if you issue a Stop Request Queue QIO to an already stopped viewport, 
the QIO will not complete until the viewport is started by an AST routine or another 
process. However, if you issue a Stop Request Queue QIO to a suspended viewport, 
the Stop Request Queue QIO will complete. 


2.15 Handling Occlusion 

In multiviewport systems, there may be instances in which two or more viewports 
overlap. The area of a viewport overlapped by another viewport is said to be 
occluded. Figure 2-9 illustrates one viewport (VP_A) occluding another (VP_B). 

Figure 2-9 Occluded Viewport 
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Only one viewport can display the overlapped area of the bitmap at a given time. 

If your application is designed to permit occlusion, it must be able to handle any 
operations directed to a viewport region that is occluded. You do this by moving 
the occluded region of the viewport into offscreen memory and performing any 
operations directed to it in offscreen memory. If, at a later time, that portion of the 
screen becomes available for display, you can then copy the up-to-date region back 
to the screen. (This is referred to as "popping" the viewport.) The following sections 
describe how to handle a simple case of occlusion. 
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2.15.1 Redefining Viewports 

An application uses the update region definition buffers to handle occlusion. A 
viewport that is originally defined as one rectangle, using a single URD, can 
be redefined as a number of rectangles (viewport regions) using a URD for each 
rectangle. The URDs provide both the absolute position of the rectangle in QDSS 
memory and the viewport-relative coordinates of the rectangles in relation to each 
other. 

Use the Define Viewport Region QIO to redefine a viewport. You can redefine an 
occluded region to be in offscreen memory (using a negative Y coordinate); because 
the drawing operations use viewport-relative coordinates, the drawing is performed 
properly. You must ensure that the negative Y coordinate you use falls within the 
range of the free.>-l area of offscreen memory (see Figure 1-4). 

Figure 2-10 illustrates the partitioning of an occluded viewport. In this example, the 
viewport is divided into three rectangles (A, B, and C). The minimum, maximum, 
and base (X,Y) coordinate pairs are stored in three definition buffers. 

The base coordinates of each accessible rectangle are in absolute device coordinates 
which are relative to the base of display memory (0,0). A base value with two 
positive coordinates indicates that the rectangle is in onscreen display memory. A 
base value with a negative Y coordinate and a positive X coordinate indicates that 
the rectangle is in offscreen memory. A base value of (-1,-1), for instance, indicates 
that the rectangle is on the deferred queue; see Section 2.18 for information about 
the deferred queue. Note that rectangle A is redefined to be in offscreen memory. 

2.15.2 Securing Exclusive Access to the Bitmap 

An application secures exclusive access to the bitmap to guarantee that two or more 
overlapping viewports do not attempt to write to the same piece of the display 
simultaneously. Before creating a viewport, your application should determine 
whether another viewport already exists in the area of the screen in which the 
viewport will be created. (Keeping track of where each viewport is on the screen is a 
bookkeeping function that is the responsibility of the application.) 

To secure exclusive access to a viewport bitmap: 

1. Stop activity on the existing viewport using the Stop Request Queue QIO. This 
must be done to ensure a known state for the subsequent steps. 

2. Redefine the regions of the existing viewport using the Define Viewport Region 
QIO. 

3. Copy the to-be-occluded region of the existing viewport to offscreen memory, 
using the Write Bitmap or Read Bitmap QIO. 
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Figure 2-10 Redefining Viewports with URDs 
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4. Update the URD definition of the existing viewport to reflect its new state. 
Redefine the occluded region to be offscreen by specifying a negative Y 
coordinate in the base value of the URD. (The negative Y value must fall within 
the range of the free area of offscreen memory shown in Figure 1-4). Remember, 
drawing can still be performed to offscreen memory. 

5. Restart the viewport using the Start Request Queue QIO. 

Once this is done, you can create the new viewport on screen and start drawing 
operations on it. 

The following example occludes one viewport with another. Exclusive access to the 
bitmap is guaranteed before the second viewport is created. The occluded region of 
the existing viewport is copied into the offscreen memory free area at (0,-200). Note 
that the transfer parameter block (TPB) is loaded using the predefined structure in 
the VWSSYSDEF file. 
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Example 2-3 Securing Bitmap Access 

PROGRAM CREATE.VIEWPORT 
IMPLICIT INTEGER*4(A-Z) 

INCLUDE ’VWSSYSDEF’ 

INCLUDE ’($I0DEF)’ 

INTEGER+2 CHAN.VPl, 

2 CHAN_VP2 

! Declare TPB 
INTEGER*2 TPB(13) 

! Declare URDs 
INTEGER*2 URD1_VP1(6), 

2 URD1_VP2(6) 

! Load URD1_VP1 buffer 
URDl.VPld) = 0 
URD1_VP1(2) = 0 
URD1_VP1(3) = 99 
URD1_VP1(4) = 99 
URD1_VP1(5) = 10 
URD1_VP1(6) = 10 

! Load URD1_VP2 buffer 
URD1_VP2(1) = 0 ! lower left corner 

URD1_VP2(2) = 0 

URD1_VP2(3) = 99 ! upper right corner 

URD1_VP2(4) = 99 

URD1_VP2(5) = 60 ! absolute coordinate base 

URD1_VP2(6) = 60 

! Define and start VPl 

CALL VIEWPORT (URD1_VP1. CHAN_VP1, VP1_ID) 


lower left corner 
upper right corner 
absolute coordinate base 


! Stop VPl 

CODE = I0$_SETM0DE 

STATUS = SYS$QI0W (. 

2 y,VAL(CHAN_VPl), 

2 */.VAL(C0DE), 

2 

2 ’/.VALdOSC.QD.STOP). 

2 y.VAL(VPl_ID), 

2 

IF (STATUS .NE. 1) THEN 

CALL LIB$SIGNAL C/.VAL (STATUS)) 
END IF 


! channel 

! QIO function code 

! QD function code 
! address of ID buffer 


(Continued on next page) 
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! Load TPB for occluded rectangle 
CALL L0AD_TPB (TPB) 

! Copy occluded rectangle into offscreen memory 
CODE = IO$_QDWRITE 
STATUS = SYS$QI0W (. 

2 ’/.VALCCHAN.VPl). ! channel 

2 y,VAL(C0DE), ! QIO function code 

2 . 

2 TPB, ! transfer block 

2 %VAL(TPB$C_BITMAP_XFR_LENGTH).) 

IF (STATUS .NE. 1) THEN 

CALL LIB$SIGNAL (’/.VAL (STATUS)) 

END IF 

! Update regions of VPl 
CALL UPDATE_REGIONS (CHAN_VP1, VP1_ID) 

! Restart VPl 
CODE = I0$_SETM0DE 
STATUS = SYS$QI0W (, 

2 •/.VAL(CHAN_VP1). 

2 •/.VAL(CODE), 

2 

2 '/.VALdOSC.QD.START). 

2 •/.VAL(VP1_ID), 

2 ...) 

IF (STATUS .NE. 1) THEN 

CALL LIB$SIGNAL C/.VAL (STATUS)) 

END IF 

! Define and start VP2 

CALL VIEWPORT (URD1_VP2, CHAN_VP2, VP2_ID) 


! channel 

! QIO function code 

! QD function code 
! address of ID buffer 


! * LOAD TPB SUBROUTINE * 

I sic :ic :|c :|c ^ :|c :|c :|c 3|c :ic ^ :|c ^ ^ 

SUBROUTINE L0AD_TPB (TPB) 

IMPLICIT INTEGER*4(A-Z) 

INCLUDE ’VWSSYSDEF’ 

! Associate the predefined structure w/ TPB 
RECORD /TPB.STRUCTURE/ TPB 


(Continued on next page) 
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! Load values 

TPB.TPB$B_TYPE = TPB$C_BITMAP^XFR 
TPB.TPB$B_SIZE = TPB$C_LENGTH 
TPB.TPB$W_X_SOURCE = 60 
TPB.TPB$W_Y_S0URCE = 60 
TPB.TPB$W_WIDTH = 50 
TPB.TPB$W_HEIGHT = 50 
TPB.TPB$W_X.TARGET = 0 
TPB.TPB$W^Y_TARGET = -200 

RETURN 
END 

! * UPDATE REGION SUBROUTINE * 

SUBROUTINE UPDATE_REGIONS (VP.CHANNEL, VIEWPORT.ID) 
IMPLICIT INTEGER*4(A-Z) 

INCLUDE ’VWSSYSDEF’ 

INCLUDE ’($I0DEF)^ 

! Declare URD 
INTEGER*2 URD(18) 

! Load URD buffer 
! First rectangle 

URD(l) = 0 ! lower left corner 

URD(2) = 0 

URD(3) = 99 ! upper right corner 

URD(4) = 49 

URD(5) = 10 ! absolute coordinate base 

URD(6) = 10 

! Second rectangle 

URD(7) = 0 ! lower left corner 

URD(8) = 49 

URD(9) = 49 ! upper right corner 

URD(10) = 99 

URD(ll) = 10 ! absolute coordinate base 

URD(12) = 59 
! Third rectangle 

URD(13) = 49 ! lower left corner 

URD(14) = 49 

URD(15) = 99 ! upper right corner 

URD(16) = 99 

URD(17) = 0 ! absolute coordinate base 

URD(18) = -200 ! (offscreen) 


! type 

! X of lower left corner 
! y of lower left corner 
! width of source 
! height of source 
! X of lower left corner 
! y of lower left corner 


(Continued on next page) 
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CODE = I0$_SETM0DE 
STATUS = SYS$QI0W (, 

2 ‘/.VALCVP.CHANNEL). ! channel 

2 y,VAL(C0DE), ! QIO function code 

2 

2 •/.VAL(IO$C_QD_SET_VIEWPORT_REGIONS), 

2 URD, ! address of URD buffer 

2 y,VAL(3 * URD$C_LENGTH) , ! length of URD buffer 

2 y.VAL(VIEWPORT_ID) ,.) ! address of VP ID 

IF (STATUS .NE. 1) THEN 

CALL LIB$SIGNAL C/.VAL (STATUS)) 

END IF 

RETURN 

END 


2.15.3 Popping an Occluded Viewport 

Bringing an occluded viewport into full view onscreen is referred to as popping a 
viewport. Popping a viewport involves copying the occluding region into offscreen 
memory and the occluded region from offscreen memory onto the screen. To pop a 
viewport, an application must take the following steps: 

1. Stop activity on the occluding viewport. 

2. Copy the occluding region into offscreen memory. 

3. Redefine the occluding viewport's URDs. 

4. Restart the occluding viewport. 

5. Stop activity on the occluded viewport. 

6. Copy the occluded region from offscreen memory onto the screen. 

7. Redefine the occluded viewport's URDs. 

8. Restart the (formerly) occluded viewport. 
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Example 2-4 Popping a Viewport 
PROGRAM POP 

IMPLICIT INTEGER*4(A-Z) 
INCLUDE ’VWSSYSDEF’ 
INCLUDE ’($I0DEF)’ 

INTEGER*2 CHAN.VPl, 

2 CHAN_VP2 

! Declare TPBs 
INTEGER*2 TPB1(13), 

2 TPB2(13). 

2 TPB3(13) 


! Declare URDs 
INTEGER*2 URD1_VP1(6). 
2 URD1_VP2(6) 

! Load URD1_VP1 buffer 
URDl.VPKl) = 0 
URD1_VP1(2) = 0 
URD1_VP1(3) = 99 
URD1_VP1(4) = 99 
URD1_VP1(5) = 10 
URD1_VP1(6) = 10 

! Load URD1_VP2 buffer 
URD1_VP2(1) = 0 
URD1_VP2(2) = 0 
URD1_VP2(3) = 99 
URD1_VP2(4) = 99 
URD1_VP2(5) = 60 
URD1_VP2(6) = 60 


! lower left corner 
! upper right corner 
! absolute coordinate base 

! lower left corner 
! upper right corner 
! absolute coordinate base 


! Define and start two overlapping viewports 


(Continued on next page) 
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! Stop VP2 (the occluding viewport) 
CODE = I0$_SETM0DE 
STATUS = SYS$QI0W (. 

2 •/.VAL(CHAN_VP2), 

2 y,VAL(C0DE), 

2 

2 y.VAL(IO$C_QD_STOP), 

2 y.VAL(VP2_ID), 

2 

IF (STATUS .NE. 1) THEN 

CALL LIB$SIGNAL C/.VAL (STATUS)) 
END IF 

! Load TPB for occluded rectangle 
CALL L0AD_TPB2 (TPB2) 


! channel 

! qiO function code 

! QD function code 
! address of ID buffer 


! Copy occluding region into offscreen memory 
CODE = IO$_QDWRITE 
STATUS = SYS$QI0W (, 

2 y.VAL(CHAN_VP2) , ! channel 

2 y.VAL(C0DE) . ! QIO function code 

2 . 

2 TPB2, ! transfer block 

2 y,VAL (TPB$C_BITMAP_XFR_LENGTH) ,) 

IF (STATUS .NE. 1) THEN 

CALL LIB$SIGNAL ('/.VAL (STATUS)) 

END IF 


! Update regions of VP2 
KEY = 2 

CALL UPDATE.REGIONS (CHAN_VP2. VP2_ID, KEY) 


! Restart VP2 
CODE = I0$_SETM0DE 
STATUS = SYS$QIOW (. 

2 y.VAL(CHAN_VP2), 

2 y.VAL(C0DE). 

2 

2 y.VAL(IO$C_QD_START), 

2 y,VAL(VP2_ID). 

2 ,,,) 

IF (STATUS .NE. 1) THEN 

CALL LIB$SIGNAL (’/.VAL (STATUS)) 

END IF 


! channel 

! qiO function code 

! QD function code 
! address of ID buffer 


(Continued on next page) 
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! Stop VPl (the occluded viewport) 

CODE = I0$_SETM0DE 
STATUS = SYS$QI0W (. 

2 '/.VALCCHAN.VPl), 

2 ’/.VALCCODE) . 

2 

2 y.VAL(I0$C_QD_ST0P). 

2 7,VAL(VP1_ID), 

2 . , 

IF (STATUS .NE. 1) THEN 

CALL LIB$SIGNAL (%VAL (STATUS)) 

END IF 

! Load TPB for occluded rectangle 
CALL L0AD_TPB3 (TPB3) 

! Copy offscreen rectangle into screen memory 
CODE = IO$_QDWRITE 
STATUS = SYS$QI0W (. 

2 •/,VAL(CHAN_VP1). ! channel 

2 %VAL(C0DE), ! QIO function code 

2 ...... 

2 TPB3j ! transfer block 

2 ’/.VAL (TPB$C_BITMAP_XFR_LENGTH) ,) 

IF (STATUS .NE. 1) THEN 

CALL LIB$SIGNAL C/.VAL (STATUS)) 

END IF 


! channel 

! QIO function code 

! QD function code 
! address of ID buffer 


! Update regions of VPl 
KEY = 3 

CALL UPDATE_REGIONS (CHAN_VP1, VP1_ID, KEY) 


! Restart VPl 
CODE = I0$_SETM0DE 
STATUS = SYS$QI0W (. 

2 •/,VAL(CHAN_VP1), ! 

2 7,VAL(C0DE). ! 

2 

2 7.VAL(I0$C_QD_START) . ! 

2 7.VAL(VP1_ID), ! 

2 ,..) 

IF (STATUS .NE. 1) THEN 

CALL LIB$SIGNAL (7,VAL (STATUS)) 

END IF 


channel 

QIO function code 

QD function code 
address of ID buffer 


(Continued on next page) 
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! * LOAD TPB2 SUBROUTINE * 2 

SUBROUTINE L0AD_TPB2 (TPB) 

IMPLICIT INTEGER*4(A“Z) 

INCLUDE ’VWSSYSDEF* 

! Associate the predefined structure w/ TPB 
RECORD /TPB^STRUCTURE/ TPB 


! type 

! X of lower left corner 
! y of lower left corner 
! width of source 
! height of source 
! X of lower left corner 
! y of lower left corner 

RETURN 

END 

j :|c 9|c 3|c ^ ^ sic 9|c)ic »|c :|c sje :)c 3|( sic ^ ^ ^ 

! * LOAD TPB3 SUBROUTINE * 3 

SUBROUTINE L0AD_TPB3 (TPB) 

IMPLICIT INTEGER*4(A-Z) 

INCLUDE ’VWSSYSDEF’ 


! Load values 

TPB.TPB$B_TYPE = TPB$C_BITMAP_XFR 
TPB.TPB$B_SIZE = TPB$C_LENGTH 
TPB.TPB$W_X_SOURCE = 60 
TPB.TPB$W_Y_SOURCE = 60 
TPB.TPB$W_WIDTH = 50 
TPB.TPB$W_HEIGHT = 50 
TPB.TPB$W_X_TARGET = 0 
TPB.TPB$W_Y_TARGET = -500 


! Associate the predefined structure w/ TPB 
RECORD /TPB.STRUCTURE/ TPB 


(Continued on next page) 
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! Load values 

TPB.TPB$B_TYPE = TPB$C_BITMAP_XFR 
TPB.TPB$B_SIZE = TPB$C_LENGTH 
TPB.TPB$W_X_SOURCE = 0 
TPB.TPB$W_Y_SOURCE = -200 
TPB.TPB$W_WIDTH = 50 
TPB.TPB$W_HEIGHT = 50 
TPB.TPB$W_X_TARGET = 60 
TPB.TPB$W_Y_TARGET = 60 

RETURN 
END 

! * UPDATE REGION SUBROUTINE * 

SUBROUTINE UPDATE.REGIONS (VP_CHANNEL, VIEWPORT.ID, KEY) 
IMPLICIT INTEGER*4(A-Z) 

INCLUDE ’VWSSYSDEF’ 

INCLUDE ’($I0DEF)’ 

! Declare URD 
INTEGER*2 URD(18) 

! Assume long URD 

URD_LENGTH = (3 * URD$C_LENGTH) 

! Key determines which URD is loaded 
IF (KEY .EQ. 1) THEN 


! type 

! X of lower left corner 
! y of lower left corner 
! width of source 
! height of source 
! X of lower left corner 
! y of lower left corner 


ELSE IF (KEY .EQ. 2) THEN 


! Redefine VP2 for 

occlusion 

! First rectangle 


URD(l) = 0 

! lower left corner 

URD(2) = 0 


URD(3) = 49 

! upper right corner 

URD(4) = 49 


URD(5) = 0 

! absolute coordinate base 

URD(6) = -500 

! (offscreen) 


(Continued on next page) 
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! Second rectangle 
URD(7) = 0 
URD(8) = 50 
URD(9) = 99 
URD(IO) = 99 
URD(ll) = 60 
URD(12) = 110 
! Third rectangle 
URD(13) = 50 
URD(14) = 0 
URD(15) = 99 
URD(16) = 49 
URD(17) = 110 
URD(18) = 60 

ELSE IF (KEY .EQ. 3) THEN 

! Redefine VPl for pop 

URD(l) = 0 ! lower left corner 

URD(2) = 0 

URD(3) = 99 ! upper right corner 

URD(4) = 99 

URD(5) = 10 ! absolute coordinate base 

URD(6) = 10 

URD.LENGTH = URD$C_LENGTH 
ELSE 


! lower left corner 
! upper right corner 
! absolute coordinate base 

! lower left comer 
! upper right corner 
! absolute coordinate base 


END IF 

CODE = I0$_SETM0DE 
STATUS = SYS$QI0W (, 

2 •/,VAL(VP_CHANNEL). ! channel 

2 y,VAL(C0DE), ! QIO function code 

2 

2 y.VAL(IO$C_QD_SET_VIEWPORT_REGIONS). 

2 URD, ! address of URD buffer 

2 y.VAL(URD_LENGTH) , ! length of URD buffer 

2 y,VAL(VIEWPORT_ID) ..) ! address of VP ID 

IF (STATUS .NE. 1) THEN 

CALL LIB$SIGNAL C/.VAL (STATUS)) 

END IF 

RETURN 

END 
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2.16 Deleting a Viewport 

When deleting a viewport, synchronization of activity is important. Your application 
must guarantee that all drawing activity to a viewport is completed before the 
viewport is deleted. Once all drawing is completed, you can deassign the associated 
channel to ensure that nothing else is written to the viewport. Finally, you may erase 
the viewport. The following sections describe each of these procedures. 

2.16.1 Synchronizing Viewport Deletion 

To guarantee that all drawing to a viewport is complete before deassigning a channel, 
an application must take the following steps: 

• Issue a Stop Viewport Activity DOP using the Insert DOP QIO (the QDWRITE 
function code with the IO$M—QD_INSERT--DOP modifier). This ensures that 
both pending operations on the DOP request queue and those in progress are 
completed before the delete. The QIO is used because it will wait for the stop 
to occur before returning control. This is done to account for the lag time in 
processing DOPs. If you did not wait for completion you might delete the 
viewport while DOPs were on the queue. 

• Deassign the associated channel, using the $DASSGN system service. 

2.16.2 Erasing a Viewport 

To erase a viewport, draw a rectangle of background color over the viewport, using 
the Fill Polygon DOP. You must use the systemwide viewport to perform this 
operation. (The channel of the viewport to be erased is already disassociated.) Take 
the following steps: 

• Assign a channel for the systemwide viewport. 

• Obtain the system information block using the Get System Information QIO. 

• Extract the systemwide viewport ID from the system information block. 

• Use the Fill Polygon DOP to draw a rectangle of background color over the 
viewport (see Chapter 5 for details about DOPs). The systemwide viewport ID is 
needed to perform this DOP on the systemwide viewport. 

The following example deletes a viewport. 



2-52 How to Program to the Driver 


Example 2-5 Deleting a Viewport 

PROGRAM DELETE.VIEWPORT 
IMPLICIT INTEGER*4(A-Z) 

INCLUDE ’VWSSYSDEF’ 

INCLUDE ’($I0DEF)’ 

! Declare external macro routine 
EXTERNAL DOP$INSQUE 

INTEGER*2 CHAN_VP1, 

2 CHAN.SYS 

! Declare TPB 
INTEGER*2 TPB(13) 

! Declare URD 
INTEGER*2 URD1^VP1(6) 

! Declare QDB descriptor and buffer 
INTEGER*4 QDB_DESC(2) 

! Load URDl.VPl buffer 

URDl^VPld) = 0 ! lower left corner 

URD1_VP1(2) = 0 

URD1_VP1(3) = 99 ! upper right corner 

URD1^VP1(4) = 99 

URD1_VP1(5) = 10 ! absolute coordinate base 

URDl^VPKe) = 10 

! Define and start VPl 

CALL VIEWPORT (URD1_VP1, CHAN.VPl, VPl.ID) 

! Draw to the viewport 


! Delete the Viewport 


! Synchronize the deletion 
! get a Stop DOP for VPl 
SIZE = (DOP$C^LENGTH) ! 

CALL GET^DOP (VPl^ID, SIZE, D0P2) 

! Call the Stop subroutine 
CALL STOP^VP (%VAL(D0P2), ! 

2 SIZE, ! 

2 VPl^ID) ! 


calculate size 


DOP address, by value 
DOP size 
viewport ID 

(Continued on next page) 
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! Insert the DOP using Insert DOP QIO 
CODE = (IO$_QDWRITE .OR. IO$M_QD_INSERT_DOP) 
STATUS = SYS$QI0W (. 

2 '/.VALCCHAN.VPl). 

2 XVALCCODE).,,, 

2 D0P2, 

2 ’/.VALCSIZE), 

2 7.VAL(VP1_ID),,,) 

IF (STATUS .NE. 1) THEN 

CALL LIB$SIGNAL (’/.VAL (STATUS)) 

END IF 

! Deassign the viewport channel 

CALL SYS$DASSGN (CHAN.VPl) ! channel 


channel 

QIO function code 
DOP address 
DOP size 
VP ID 


! Obtain a channel for the systemwide VP 

CALL SYS$ASSIGN (’SYS$WORKSTATION’, ! device name 

2 CHAN.SYS,,) ! channel 


! Get the systemwide viewport ID 

! Get the QDB 

CODE = I0$_SENSEM0DE 

STATUS = SYS$QI0W (. 

2 •/.VAL(CHAN_SYS). ! channel 

2 y.VAL(C0DE). ! QIO function code 

2 

2 ’/.VALdOSC.QV.GETSYS), 

2 QDB_DESC,,.,) ! address of descriptor 

IF (STATUS .NE. 1) THEN 

CALL LIB$SIGNAL (‘/.VAL (STATUS)) 

END IF 


! Extract the ID from the QDB 

SYS.ID = EXTRACT_SYS_ID (•/.VAL(QDB_DESC(2))) ! pass address by value 


! Get a Fill Polygon DOP 

SIZE = (DOP_POLY$C_LENGTH) ! calculate size 

CALL GET_D0P (SYS.ID, SIZE. D0P3) 


! Call the Fill Polygon subroutine to erase VPl border 
CALL F_P0LY (7.VAL(D0P3). ! DOP address, by value 

2 y,VAL(D0P3+D0P$C_LENGTH). ! var. block address 

2 SIZE) ! DOP size 


! Queue the DOP by calling a MACRO subroutine 

CALL DOP$INSQUE (y.VAL(D0P3). ! DOP address, by value 

2 SYS_ID) ! viewport ID 

(Continued on next page) 
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! Get OOP Subroutine 

SUBROUTINE GET.DOP (VIEWPORT_ID, SIZE. OOP) 

IMPLICIT INTEGER*4(A-Z) 

! Declare external macro routine 
EXTERNAL DOPSREMQUE 

DOP = DOP$REMQUE (VIEWPORT.ID, 

2 SIZE) 

! If none on return queue, calculate size and allocate one. 

IF (DOP .EQ. 0) THEN 

CALL TEST.SIZE (7.VAL(VIEWP0RT_ID), ! viewport ID > return Q 

2 SIZE) 

! Allocate appropriate size DOP 
CALL LIB$GET_VM (SIZE. 

2 DOP) 

END IF 

RETURN 

END 

! * TEST.SIZE SUBROUTINE * 

SUBROUTINE TEST_SIZE (REQ.SIZE) 

IMPLICIT INTEGER=t=4(A-Z) 

INCLUDE ’VWSSYSDEF’ 

! Associate the predefined structure w/ REQ 
RECORD /REQ.STRUCTURE/ REQ 

IF (SIZE .GT. REQ.REQ$W_SMALL_DOP_SIZE) THEN 
SIZE = REQ.REq$W_LARGE_DOP_SIZE 
ELSE 

SIZE = REQ.REC|$W_SMALL_DOP_SIZE 
END IF 

RETURN 

END 


(Continued on next page) 
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I 3|c :|c:|c 3|c :ic 3|c ^ 3|c 3|e ^ :ic ^ :|c 3|c 3|c ^ 9|c ^ :)c 3|c sic 3|c jjc }|c ^ :)c ^ 

! * EXTRACT_SYS_ID SUBROUTINE * 

FUNCTION EXTRACT_SYS^ID (QDB) 

IMPLICIT INTEGER*4(A"Z) 

INCLUDE ’VWSSYSDEF* 

! Associate the predefined structure w/ QDB 
RECORD /QVB.QDSS^STRUCTURE/ QDB 

EXTRACT_SYS_ID = QDB.QDB$L^SYSVP 

RETURN 

END 

! * STOP^VP SUBROUTINE * 

I 3|C S|C sic 3{C 3|C S|C sic 3|C 3|C S|C 3|C 3|C S|C S|C Sje S|C S|C sic sic S|C S|C 3|C 

SUBROUTINE ST0P_VP (OOP, SIZE. VIEWPORT.ID) 
IMPLICIT INTEGER*4(A-Z) 

INCLUDE ’VWSSYSDEF’ 

! Associate the predefined fixed structure w/ DOP 
RECORD /DOP_STRUCTURE/ DOP 

! Load the Common block 
DOP.DOP$W_SIZE = SIZE 
DOP.DOP$W_FLAGS = 0 

DOP.DOP$W_MODE = WRIT$M_NO_SRC_COMP + 10 
DOP.DOP$L_MASK = -1 
DOP.DOP$L_SOURCE_INDEX = -1 
DOP.DOP$L_FCOLOR = 253 
DOP.DOP$L_BCOLOR = 252 
DOP.DOP$W_VP_MAX_X = 99 
DOP.DOP$W_VP_MAX_Y = 99 
DOP.DOP$W_DELTA_X = 0 
DOP.DOP$W_DELTA_Y = 0 
DOP.DOP$W_VP_MIN_X = 0 
DOP.DOP$W_VP_MIN_Y = 0 


(Continued on next page) 
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Example 2-5 (Cont.) Deleting a Viewport 

! Load the Stop values 
DOP.DOP$W_ITEM_TYPE = D0P$C_ST0P 
D0P.D0P$W_0P_C0UNT = 1 
DOP.DOP$L_DRIVER_VP_ID = VIEWPORT_ID 

RETURN 

END 

I :ic 9|c :|c 3|c :|c :|c :)c :|c:|c :|c 3ic 9|c 3|c :|c :|c 

! * F_P0LY SUBROUTINE * 

SUBROUTINE F_P0LY (DOP, DOP.VAR, SIZE) 

IMPLICIT INTEGER*4(A-Z) 

INCLUDE ’VWSSYSDEF’ 

! Associate the predefined fixed structure w/ DOP 
RECORD /DOP_STRUCTURE/ DOP 

! Associate the predefined variable structure w/ D0P_VAR 
RECORD /D0P_P0LY_ARRAY/ DOP.VAR 

! Load the Common block 
D0P.D0P$W_SIZE = SIZE 
D0P.D0P$W_FLAGS = 0 

D0P.D0P$W_M0DE = WRIT$M_NO_SRC_COMP + 10 
D0P.D0P$L_MASK = -1 
D0P.D0P$L_S0URCE_INDEX = -1 
D0P.D0P$L_FC0L0R = 252 
D0P.D0P$L_BC0L0R = 252 

! Load the POLYGON values 
DOP.DOP$W_ITEM_TYPE = D0P$C_FILL_P0LYG0N 
D0P.D0P$W_0P_C0UNT = 1 
DOP.DOP$L_BITMAP_ID = 0 ! no bitmap 

D0P_VAR.D0P_P0LY$W_LEFT_X1 = 10 
D0P_VAR.D0P_P0LY$W_LEFT_Y1 = 10 
D0P_VAR.D0P_P0LY$W_LEFT_X2 = 10 
D0P_VAR.D0P_P0LY$Vf_LEFT_Y2 =110 

D0P_VAR.D0P_P0LY$W_RIGHT_X1 =110 
D0P_VAR.D0P_P0LY$W_RIGHT_Y1 = 10 
D0P_VAR.D0P_P0LY$W_RIGHT_X2 =110 
D0P_VAR.D0P_P0LY$W_RIGHT_Y2 = 110 

RETURN 

END 
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2.17 Moving a Viewport 

The QDSS driver does not provide support to move a viewport or change its size. 
However, an application can define a move operation. 

To move a viewport, an application must perform the following steps: 

1. Copy the contents of the old viewport to an area in the offscreen bitmap. 

2. Delete the old viewport. 

3. Create a new viewport. 

4. Copy the data from the offscreen bitmap to the new viewport. 

How to perform all of these functions is shown in the previous examples. 


2.18 Using the Deferred Queue 

When a viewport is occluded and the free area of offscreen memory is already full 
of occluded regions, the only way to ensure that a drawing operation is performed 
for the region is to place it on the deferred queue. (Again, keeping track of offscreen 
memory usage is the responsibility of the application.) 

To place a region on the deferred queue: 

1. Copy the region to processor memory using the Read Bitmap QIO. This saves 
the state of the region until it can be updated. 

2. Redefine it with the Define Viewport Region QIO setting the absolute base 

coordinates to When placing a region on the deferred queue, the relative 

coordinates are not important. These base coordinates indicate to the driver that 
operations for the region are to be stored on the deferred queue. 

If an application plans to use the deferred queue, it should call the Notify Deferred 
Queue Full QIO before using the queue. This QIO permits you to notify an 
application when the deferred queue is full. (It prevents a deferred region from 
consuming too much memory.) 

Your application should execute operations stored on the deferred queue either when 
QDSS memory becomes available or when notified that the queue is full. To execute 
an operation on the deferred queue: 

1. Copy the region back into offscreen memory using the Write Bitmap QIO. 

2. Redefine the region using the Define Viewport Region QIO. 

3. Execute operations stored on the queue using the Execute Deferred Queue QIO. 
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If no memory is available when the queue is full, swap another region out of 
offscreen memory and onto the deferred queue, at least until the queue is executed. 

Note that if a viewport is occluded in more than one place, you may have to execute 
the same deferred queue — multiple times. That is, update the first region at one point, 
and update the other region with the same operations later. To do this, define a 
region on the deferred queue when you redefine the first region to be in offscreen 
memory for deferred queue execution. This will inform the driver that the viewport 
still has an occluded region and will prevent it from deleting the deferred queue. 

After the deferred queue drawing operations have been executed to all the deferred 
regions of a viewport, delete the drawing operations from the deferred queue with 
the Delete Deferred Queue Operation QIO. Also, when an application deletes a 
viewport with a region on the deferred queue, delete the deferred queue drawing 
operations for that region. 


2.19 Using Color 

The QDSS driver uses several planes of memory to display color. Corresponding 
points in each plane of memory are mapped to a single pixel on the display. The 
number of memory planes configured with a system determines the depth or Z-mode 
of a pixel and the number of colors that can be simultaneously displayed. 

A driver configured with n planes of memory is capable of displaying 2**n colors. 
The QDSS driver can be configured with four or eight planes of memory. Hence, a 
four-plane system can display 16 simultaneous colors and an eight-plane system 256. 

The total number of different colors a system could display is specified by a longword 
in the QDSS QVB block. The QDSS driver is capable of defining a maximum of 
2**24 colors, but only 16 or 236 colors may be on the screen at any one time. 

Each color that can be displayed is represented by a value in the hardware color 
map (also known as the hardware look-up table). On color systems, a color is 
defined by three 16-bit intensity values, one for each primary color. On intensity 
systems, a color is represented by only one 16-bit value. The low-order eight bits of 
these values are ignored. The high-order eight bits are used to represent the actual 
intensity values. Hence, intensity values range from 0 to 255. 

2.19.1 Informing the Driver About Color 

Before an application can use the hardware color map, it must tell the driver which 
type of color system it is using. To identify a system as either color or intensity 
based, use the Set Color Characteristics QIO, specifying the second unique parameter 
as either 0 (indicating a color system) or 1 (indicating an intensity system). Once this 
has been determined, the driver will only accept Set Color Map Entries QIO requests 
that match this setting. All other Set Color Map Entries QIOs are rejected. 
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2.19.2 Manipulating Color Map Values 

The values used to represent pixels onscreen are used as indexes into the hardware 
color map. Pixel values are read in the Z-mode direction — for example, if only the 
first three planes of a pixel are used and the bits in the first and third planes are set, 
the resulting pixel value is 101 (binary). This value indexes into the fifth value in the 
hardware color map. Figure 2-11 illustrates how this works. 

Figure 2-11 Indexing the Hardware Color Map 


Hardware Color Map 




Intensity Values 


ZK-5352-86 


If your application is not using the UIS environment, it must load any values it uses 
into the hardware color map. To load values into the hardware color map, use the 
Set Color Map Entries QIO; specifying an index into the color map at which to begin 
initializing, the address of the buffer containing the desired intensity values, and the 
length of the buffer. You may call this QIO at any time to redefine the values in the 
color map. 

To determine the current values of the hardware color map, use the Get Color Map 
Entries QIO; specifying an index into the color map at which to begin retrieving 
information, the address of the buffer to hold the returned intensity values, and the 
length of the buffer. 
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Chapter 3 

QVSS/QDSS Common QIC Interface 

This chapter contains descriptions of the QIO calls that you can use with the QVSS 
and QDSS drivers. The QIO descriptions appear in alphabetical order. The following 
list organizes the QIOs in functional groups. 


Functional Group 

QIO Name 

Controlling the Keyboard 

Enable Keyboard Input 

Enable Keyboard Sound 

Modify Keyboard Characteristics 

Controlling Input 

Enable Input Simulation 

Get Next Input Token 

Controlling the Pointer 

Define Pointer Cursor Pattern 

Enable Button Transition 

Enable Pointer Motion 

Controlling the Screen 

Initialize Screen 

Modify Systemwide Characteristics 

Enable Function Keys 

Controlling the Tablet 

Enable Data Digitizing 

Controlling User Entry Lists 

Enable User Entry 

Obtaining Information 

Get Keyboard Characteristics 

Get Number of List Entries 

Get System Information 

Using Compose Keys 

Load Compose Sequence Table 

Revert to Default Compose Table 

Using Soft Keys 

Load Keyboard Table 

Revert to Default Keyboard Table 
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3.1 How to Use This Chapter 

Before attempting to call the QIOs described in this chapter, you should read 
Chapters 1 and 2 of this manual, and familiarize yourself with Appendixes A, B, 
and H of this manual. Chapters 1 and 2 describe the general operation of the QIOs. 
Appendixes A and B contain pictures and descriptions of the data types that you pass 
to the driver through the PI to P6 parameters of several of the QIOs. Appendix H 
contains a complete description of the SYS$QIO system service. 

3.1.1 QIO Description Format 

The QIO descriptions contained in this chapter follow a strict format. You should 
use them as reference material when you are coding a specific QIO. 

The following list notes the main headings in each QIO description and describes the 
type of information that appears there. 

• QIO Name — Name of the QIO described. Appears in each description. 

• Overview — A brief description of the operation the QIO performs. Appears in 
each description. 

• Format — The format of the call to SYS$QIO. This format line contains the QIO 
function code you must pass to SYS$QIO to perform the desired operation. 

Arguments in brackets are optional arguments. In some programming languages, 
such as MACRO, you do not have to specify optional arguments; when you omit 
them, the assembler supplies a default value of 0. Some other programming 
languages, such as FORTRAN, do not allow you to omit optional arguments; you 
must pass a value of 0 for any argument you do not want to specify. Check the 
documentation for your programming language to see how it handles optional 
arguments. Appears in each description. 

• Unique Parameters — List of the information that you must pass to the driver 
through $QIO's PI to P6 parameters. Each parameter description also tells you 
whether the parameter is required or optional. Appears in each description. 

• Description — Additional information about the operation of the QIO call. 
Optional. 

• Example — Example of the QIO. Optional. 
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Define Pointer Cursor Pattern 

Defines the pointer cursor pattern for a given region on the physical screen. 
When the cursor enters that region, the new cursor pattern takes effect. 
Other arguments allow the user to select the cursor style and reposition the 
pointer cursor. 


Format 

SYS$QIO [efn] ,chan ,IO$-SETMODE ,[iosb] ,[astadr] 
,[astprm] ,p 1 [,p2] [,p3] [,p4] [,p5] [,p6] 


Unique Parameters 

P1 — IO$C^QV^SETCURSOR 

The function code that identifies the action that the QIO perfornas. This 
parameter must be specified. 

To modify the action of the QIO, you can OR the IO$C_QV__SETCURSOR 
function code with one of the following optional function modifiers: 


Function Modifier Action 


IO$M_QV_BIND 


IO$M_QV_DELETE 


IO$M_QV_LAST 


Binds the pointer to the region specified in P6. 
Once the pointer enters the specified region, it 
cannot move outside the region's borders. If the 
region becomes occluded, the pointer is no longer 
bound to the region. 

Deletes the specified pointer cursor pattern 
request. Any data contained in the type-ahead 
buffer is delivered to the specified AST address 
before the delete operation is executed. 

Places the specified pointer cursor pattern request 
last in the entry list. If IO$M_QV_LAST is not 
specified, the request is placed first in the list. 

If an outstanding pointer cursor pattern request 
exists for the channel, it is updated to reflect the 
new entry. 
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Function Modifier 

Action 

IO$M_QV_LOAD_DEFAULT 

Makes the specified cursor pointer the system 
default cursor pointer. If you specify this function 
modifier, the system ignores any screen region 
you specify in P6. 

IO$M_QV_USE_DEFAULT 

Requests that the system use the system default 
cursor pointer when the region specified in P6 
becomes active. If you specify this function 
modifier, the system ignores any arguments you 
specify in P2, P4, and P5. 

IO$M_QV_TWO_PLANE_ 

Indicates the system is loading a multiplane cursor 

CURSOR 

pattern. Use this modifier to load a cursor pattern 
on a QDSS system. Refer to the Description 
section for more information on multiplane 


cursors. 


P2 — address of bitmap image 

This parameter is either a 16-word array or, on multiplane cursor systems, 
a 32-word array. The QVB contains a field that allows you to determine 
whether yours is a single-plane or multiplane system. Use the Get System 
Information QIO to access this field. (See Description section.) 

This is an optional parameter. 

P3 — address of new cursor position 

This parameter is a longword that points to a two-longword array that 
defines the new cursor position. The first longword specifies the X coordinate 
of the new cursor position in pixels. The second longword specifies the 
Y coordinate of the new cursor position in pixels. The following diagram 
shows the data structure that defines the new cursor position. 


X position on physical screen 


Y position on physical screen 


Field 

Use 

X position on physical screen 

Y position on physical screen 

Specifies X coordinate in pixels 

Specifies Y coordinate in pixels 


If P3 is 0, the pointer cursor is not repositioned. 
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P4 — address of pointer cursor hot spot definition 

This parameter is an address that points to a two-longword array that 
defines the pointer cursor hot spot, which is that point within the 16- x 16- 
pixel cursor display region that is the actual cursor position. The following 
diagram shows the data structure that defines the cursor hot spot. 


X offset 


Y offset 


Field Use 

X offset The X offset in pixels from the upper left corner of the pointer pattern 

to the active point. 

Y offset The Y offset in pixels from the upper left corner of the pointer pattern 

to the active point. 


P5 — vaiue that defines cursor styie 

This parameter is a longword value in the range 0 through 3 that defines 
how the cursor is presented against the background screen. The following 
table lists each value and the style it denotes. 


Value Style 

0 Dynamic NAND. The background under the cursor "hot spot" is examined 

and, if it is black (all off), the cursor is NANDed with the background. If 
the background is not black, the cursor is ORed with the background. 

1 Dynamic OR. The background under the cursor "hot spot" is examined 
and, if it is black (all off), the cursor is ORed with the background. If the 
background is not black, the cursor is NANDed with the background. 

2 NAND. The cursor is always NANDed with the background screen. 

3 OR. The cursor is always ORed with the background screen. 


This parameter is ignored for multiplane cursor systems. 

P6 — address of screen rectangie vaiues biock 

This parameter is a longword that points to a screen rectangle values block. 
This block defines a rectangle on the screen. The following diagram shows 
the data structure that defines the screen rectangle. 
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Field 

Use 

MINX (left side value) 

Pixel value for left side of rectangle 

MINY (bottom side value) 

Pixel value for bottom side of rectangle 

MAXX (right side value) 

Pixel value for right side of rectangle 

MAXY (top side value) 

Pixel value for top side of rectangle 

If you do not specify P6, 
used. 

a default rectangle that covers the entire screen is 


Description 

When the pointer cursor moves outside a currently active rectangle, a special 
signal notifies the process that the cursor has left the region. 

The QVSS and QDSS drivers allow you to specify a pointer cursor pattern 
that defines the shape of the cursor (QDSS systems use a multiplane cursor 
which is described in the following section). The shape can be in the form of 
a block, a cross, an arrow, or any other desired configuration. You can also 
define the cursor style (how the cursor is presented against the background 
screen) and the location of the cursor hot spot (the point within the cursor 
pattern region that is the actual cursor position). In addition to moving the 
cursor with the pointer, you can also reposition the cursor by specifying new 
X and Y cursor coordinates. 

Multiplane Cursor Patterns 

If your system uses a multiplane cursor (QDSS), you may specify a 32-word 
array as a cursor pattern. Currently, multiplane cursors consist of two planes. 
Typically, you use two planes to prevent the cursor from disappearing when 
it is moved over varying backgrounds. To understand how the two planes 
work, think of the 32-word array as two 16-word arrays, array A and array 
B. 

The bit pattern in array A is determined in the following way: 

• A 1 in a bit indicates that the corresponding pixel be filled. 
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• A 0 in a bit indicates that whatever is on the screen at the corresponding 
pixel should show through (remember, the cursor is overlaid on the 
screen). 

The bit pattern in array B uses the the bits set to 0 in array A as a mask; 
those corresponding bits are ignored in array B. The remaining bit pattern in 
array B is determined in the following way: 

• A 1 in a bit indicates that the corresponding pixel be filled with the 
background color. 

• A 0 in a bit indicates that the corresponding pixel be filled with the 
foreground color. 


Example 


The example that follows shows the typical assignment of a pointer cursor 
region. 


qV$CURSORl: 

.WORD 

.WORD ''bllllllllllllllll 
.WORD 

.WORD ^bllllllllllllllll 

.WORD ^bllllllllllllllll 

.WORD 

.WORD 

.WORD 

.WORD 

.WORD 

.WORD ^bllllllllllllllll 

.WORD "bllllllllllllllll 

.WORD 

.WORD 

.WORD 

.WORD 


INITIAL 16 X 16 CURSOR 
PATTERN 
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REGIONl: 


; CURSOR REGION 1 

.LONG 

20 


.LONG 

20 


.LONG 

300 


.LONG 

300 



20$: 

MOVL 

#IO$C_QV_SETCURSOR.RO 

DEFINE CURSOR 1 


$qiOW_S CHAN=CUR_CHAN1,- i 

ASSIGNED CHANNEL 



FUNC=#IO$_SETMGDE,- 

SET MODE qiO 



P1 =(R0).- 

CURSOR PATTERN REQUEST 



P2=#QV$CURS0R1.- 

CURSOR DESCRIPTION 



P6=#REGI0N1 

CURSOR REGION 


BLBS 

R0,30$ 

NO ERROR IF SET 


BRW 

ERROR 


30$: 

MOVL 

#IO$C_QV_SETCURSOR.RO 

; DEFINE CURSOR 2 


$QIOW_S CHAN=CUR_CHAN2,- ; 

: SECOND ASSIGNED CHANNEL 



FUNC=#IQ$_SETMODE,- 
P1=(R0) 

P2=#QV$CURS0R2,- 

P6=#REGI0N2 



BLBS 

R0.40$ 

: NO ERROR IF SET 


BRW 

ERROR 
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Enable Button Transition 

Enables repeating pointer button ASTs for the process on the specified 
channel. If this request has the highest priority for the specified rectangle, 
each button transition delivers an AST when the pointer cursor enters that 
area of the physical screen. 


Format 

SYS$QIO [efn] ,chan ,IO$-SETMODE ,[iosb] ,[astadr] 
,[astprm] ,p 1 ,p2 [,p3] [,p4] [,p5] [,p6] 


Unique Parameters 

PI — mC^QV^ENABUTTON 

The function code that identifies the action that the QIO performs. This 
parameter must be specified. 

To modify the action of the QIO, you can OR the IO$C_QV-JENABUTTON 
function code with one of the following optional function modifiers: 


Function Modifier 

Action 

IO$M_QV_DELETE 

Deletes the specified pointer button request. Any data 
contained in the type-ahead buffer is delivered to the 
specified AST address before the delete operation is 
executed. 

IO$M_QV_LAST 

Places the specified pointer button request last in the 
list. If IO$M_QV_LAST is not specified, the request is 
placed first in the list. If an outstanding pointer button 
request exists for the channel, it is updated to reflect 
the new priority. 

IO$M_QV_PURG_TAH 

Purges the type-ahead buffer of any existing pointer 
button transitions. 


P2 — address of a pointer button AST specification biock 

This parameter is a longword that points to a pointer AST specification block. 
This block specifies a user-supplied AST routine that is notified each time a 
pointer button transition occurs. 

The following diagram shows the data structure that specifies a pointer 
button AST. 
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AST service routine address 


AST parameter 


access mode 


input token address 


Field Use 

AST service routine address The address of the AST service routine is 0 if 

no AST routine is required. If no AST routine 
is specified, input is stored in the type-ahead 
buffer, and delivered either when an AST 
region is declared, or when a Get Next Input 
Token QIO is issued. The type-ahead buffer 
holds 32 input tokens or characters. 

AST parameter The user-defined AST parameter is delivered 

to the AST routine. The driver does not 
examine it. 

access mode The access mode at which to deliver the AST. 

It is maximized with the current access mode. 
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Field 

Use 

input token address 

The input token address is the address of a 
longword that receives an input token when 
an AST routine is called. Word 0 of the 


longword receives token or character data. 

The token is a decimal value indicating which 
button is activated. The values are assigned 
to the pointer buttons sequentially, starting 
with the select button, which is always 400. 
The driver stores the token in the low-order 


word of the longword. 


Bit 15 of the high-order word determines 
whether the transition is up or down; 1 
equals down, 0 equals up. The rest of the 
high-order word contains more control 
information that can be used to determine if 
the 1 Shift 1 , Ictrll , or I Lock! kevs are depressed. 
You can use these keys as meta-keys (keys 
used in combination). Bit 14 corresponds 
to the 1 Shift 1 kev, bit 13 corresponds to the 

Ictrll key, and bit 12 corresponds to the 
iLockI kev. When the bit is set, the kev is 
down. 


This parameter must be specified. 

P3 — must be 0 

P4 — address of a pointer button characteristics biock 

This parameter is a longword that points to a pointer button characteristics 
block. This block specifies which button-related characteristics to enable or 
disable for the button region. When the region becomes active, the specified 
characteristics become active. 
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The following diagram shows the data structure that specifies pointer button 
characteristics. 


enabled characteristics mask 


disabled characteristics mask 


0 


0 


Field 

Use 


enabled characteristics mask 

disabled characteristics mask 

Longword of characteristics to be enabled. 
Longword of characteristics to be disabled. 

The pointer button characteristics, which are 
defined by the $QVBDEF macro, consist of the 
following bit: 


Characteristic 

Meaning 


QV$M_BUT_ 

UPTODOWN 

After a pointer button down 
transition occurs, the current 
pointer button request receives 
all future pointer button 
transitions until all pointer 
buttons return to the up position 
(regardless of the position of the 
pointer cursor on the physical 
screen). If this characteristic 
is disabled, then each up and 
down transition is delivered 
to whichever button request is 
active for the current pointer 
cursor position. Default is on. 

0 

0 

This longword must be zero. 

This longword must be zero. 


P5 — must be 0 
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P6 — address of a screen rectangle values block 

This parameter is a longword that points to a screen rectangle values block. 
This block defines the area on the physical screen for which the specified 
button transition is enabled. 

The following diagram shows the data structure that defines the screen 
rectangle. 



Field 

Use 

MINX (left side value) 

MINY (bottom side value) 
MAXX (right side value) 

MAXY (top side value) 

Pixel value for left side of rectangle 

Pixel value for bottom side of rectangle 

Pixel value for right side of rectangle 

Pixel value for top side of rectangle 


This parameter is optional. If you do not specify a screen rectangle values 
block, a default rectangle that covers the entire screen is used. 


Description 

The QVSS and QDSS drivers support a multibutton pointer. The drivers 
allow a process to enable a pointer button request to signal the occurrence 
of a pointer button transition, either up or down. A token is passed to the 
specified AST routine to signal which button made a transition, and the 
type of transition (up or down). Many applications are only interested in 
pointer button events that occur in a specific region of the physical screen. 
The P6 parameter of the pointer button request specifies a rectangle on 
the physical screen. This rectangle defines the area where the application 
is interested in pointer button transitions. If rectangles for pointer button 
requests for multiple channels (or processes) overlap, priority is given to the 
first rectangle on the list. 
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Example 




The example that follows shows the typical programming and use of pointer 


button ASTs. 



SET.BUTTONAST: 




$ASSIGN_S DEVNAM=WS_DEVNAM,- 

- ; ASSIGN CHANNEL USING 



CHAN=BUT_CHAN 

LOGICAL NAME AND 

CHANNEL NUMBER 


BLBS 

R0,10$ 

NO ERROR IF SET 


BRW 

ERROR 

ERROR 


10$: MOVL 

#IO$C_C|V_ENABUTTON. RO 



$QI0W_S 

CHAN=BUT.CHAN,- 

FUNC=#I0$.SETM0DE,- 

P1=(R0),- 

P2=#BUT_BL0CK,- 

P6=#BUT_REGI0N 



BLBS 

R0.20$ 

NO ERROR IF SET 


BRW 

ERROR 



20$; RSB 

BUT.BLOCK; 


BUTTON AST 

SPECIFICATION BLOCK 


.LONG 

BUT^AST 

AST ADDRESS 


.LONG 

0 

AST PARAMETER 


.LONG 

0 

ACCESS MODE 


.LONG 

BUTTON 

BUTTON INFORMATION 

LONGWORD 


BUT_REGION: 


AST REGION 


.LONG 

20 



.LONG 

20 



.LONG 

300 



.LONG 

300 
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Enable Data Digitizing 

If the system pointing device is a tablet, the Enable Data Digitizing QIO 
allows you to use the tablet as a data digitizer. 


Format 

SYS$QIO [efn] ,chan ,IO$-SETMODE ,[iosb] Jastadr] 
,[astprm] ,p1 ,p2 ,p3 [,p4] ,p5 [,p6] 


Unique Parameters 

PI — IO$C-OV-ENABLE-DIGmZING 

The function code that identifies the action that the QIO performs. This 
parameter must be specified. 

To modify the action of the QIO, you can OR the IO$C-_QV_ENABLE_ 
DIGITIZING function code with the following optional function modifier: 


Function Modifier Action 

IO$M_-QV_DELETE Deletes the specified data digitizing request. Any data 

contained in the type-ahead buffer is delivered to the specified 
AST address before the delete operation is executed. 


P2 — address of a pointer movement AST specification biock 

This parameter is a longword that points to a pointer movement AST 
specification block. This block specifies a user-supplied AST routine that is 
notified when pointer movement occurs inside the data rectangle you specify 
in P6. The pointer position is reported using the best granularity in which 
the device can report. 



3-16 QVSS/QDSS Common QIC Interface November 1986 

Enable Data Digitizing 


The following diagram shows the data structure that specifies a pointer 
movement AST for the tablet. 


AST service routine address 


AST parameter 


access mode 


address of new pointer cursor position 


Field 

Use 

AST service routine address 

The address of the AST service routine is 0 
if no AST routine is required. No buffering 
of data in the type-ahead buffer occurs for 
pointer motion ASTs. 

AST parameter 

The user-defined AST parameter is delivered 
to the AST routine. The driver does not 
examine it. 

access mode 

The access mode at which to deliver the AST 
is maximized with the current access mode. 

address of new pointer cursor 

The fourth longword contains the address 

position 

of a longword to receive the new pointer 
cursor position when the AST routine is 
called. (If your application does not need 
this information, specify a 0.) The low-order 
word receives the new X pixel location of the 
pointer cursor; the high-order word receives 
the new Y pixel location of the cursor. The 
range of X is defined in the qvb$W— tablet- 
width field of the QVB block; the range of Y 
is defined in the qvb$W— tablet—height field of 
the QVB block. 


This is an optional parameter. 

P3 — address of a pointer button AST specification block 

This parameter is a longword that points to a pointer button AST 
specification block. This block specifies a user-supplied AST that is notified 
when a button transition occurs. 
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( 

The following diagram shows the data structure that specifies the pointer 
button AST for the tablet. 
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Field Use 

input token address The input token address is the address of a 

longword that receives an input token when 
an AST routine is called. Word 0 of the 
longword receives token or character data. 
The token is a decimal value indicating which 
button was activated. The values are assigned 
to the pointer buttons sequentially starting 
with the select button, which is always 400. 
The driver stores the token in the low-order 
word of the longword. Bit 15 of the high- 
order word determines whether the transition 
is up or down; 1 equals down, 0 equals up. 

The rest of the high-order word contains 
more control information that can be used 
to determine if the I Shift | , |ctrl| , or I Lock | keys 
are depressed. You can use these keys 
as meta-keys (keys used in combination). 

Bit 14 corresponds to the I Shift | key, bit 13 
corresponds to the I Ctrl | k ey, and bit 12 
corresponds to the I Lock | key. When the bit is 
set, the key is down. 

This is an optional parameter. 

P4, PS — must be 0 

P6 — address of a data rectangle values block 

This parameter is a longv^ord that points to a data rectangle values block. 

This block defines the active rectangle on the tablet. The origin (0,0) of the 

tablet is the lower left-hand comer. 

The following diagram shows the data structure that defines a data rectangle. 


MINX (left side value) 
MINY (bottom side value) 
MAXX (right side value) 


MAXY (top side value) 
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Field 

Use 

MINX (left side value) 

MINY (bottom side value) 

MAXX (right side value) 

MAXY (top side value) 

Pixel value for left side of rectangle 

Pixel value for bottom side of rectangle 

Pixel value for right side of rectangle 

Pixel value for top side of rectangle 


This parameter is optional. If you do not specify a data rectangle values 
block, a default rectangle that covers the entire tablet is used. 


Description 

Only the process that issues the data digitizing request may change or cancel 
it. Upon process deletion, any outstanding data digitizing is canceled. 

Only one data digitizing region may be active at a time. When one process 
has declared a data digitizing region, attempts by other processes to declare 
an additional data digitizing region fail. 
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Enable Function Keys 

Allows the windowing system to access function keys FI through F5, which 
are reserved for workstation control functions and should not be used in 
application programs. These keys are defined by the driver, which, in 
addition to informing the owner of the key of the keypress, performs special 
functions. 


Format 

SYS$QIO [efn] ,chan ,IO$-SETMODE ,[iosb] ,[astadr] 
,[astprm] ,p1 ,p2 ,p3 [,p4] [,p5] [,p6] 


Unique Parameters 

P1 — IO$C-QV-ENAFNKEY 

The function code that identifies the action that the QIO performs. 

This parameter must be specified. 

P2 — address of a reserved function keystroke AST specification 
biock 

This parameter is a longword that points to a reserved function keystroke 
AST specification block. This block specifies a user-supplied AST routine 
that is notified each time a keystroke occurs. 

The following diagram shows the data structure that specifies a reserved 
function keystroke AST. 


AST service routine address 


AST parameter 


access mode 


input token address 
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Field 

Use 

AST service routine address 

The address of the AST service routine. 
Specify 0 if no AST routine is required. If no 
AST routine is specified, input is stored in 
the type-ahead buffer, and delivered either 
when an AST region is declared, or when a 
Get Next Input Token QIO is issued. The 
type-ahead buffer holds 32 input tokens or 
characters. 

AST parameter 

The user-defined AST parameter delivered 
to the AST routine. The driver does not 


examine it. 

access mode 

The access mode at which to deliver the AST. 
It is maximized with the current access mode. 

input token address 

The address of a longword that receives an 
input token when an AST routine is called; 
word 0 of the longword contains token data 
defined by the $SMGDEF macro for these 
function keys. By default, an AST is only 
signaled on a down transition. 


This parameter must be specified. 

P3 — symbolic name for function key to associate with request 

This parameter is a symbolic name that indicates the function key to associate 
with this request. The following bits are defined: 


Key Value 

Function 

QV$M_KEY_F1 

Driver signals AST and toggles keyboard Hold Screen lamp. 

QV$M_KEY_F2 

Operator screen. If the SYSGEN parameter WS__OPAO is set 
to 1, toggles between the workstation screen and the operator 


screen. 

QV$M_KEY_F3 

Switch window. If an alternate windowing system is enabled, 
the driver signals an AST and toggles between the windowing 
systems. (This applies to monochrome VAXstation I and II 
workstations.) 

QV$M_KEY_F4 

The driver signals an AST. 

QV$M_KEY_F5 

The driver signals an AST. 


P4, PS, P6 — must be 0 
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Example 

The following example shows typical programming for the F5 function key. 


10$: MOVL #IO$C.QV.ENAFNKEY.RO 

SQIOW.S CHAN=FNKEY^F5.CHAN,- 
FUNC=#I0$_SETM0DE.- 
P1=(R0).- 
P2=#FNKEYJL0CK.- 
P3=#QV$M^KEY^F5 
BLBS R0.30$ 

BRW ERROR 


FUNG KEY REQUEST TO RO 
ASSIGNED CHANNEL 
SET MODE QIO 
FUNCTION KEY REQUEST 
AST SPEC BLOCK 
KEY IS F5 
NO ERROR IF SET 


FNKEY.BLOCK: 

.LONG F5«AST 
.LONG F5.ACK 
.LONG 0 
.LONG CHARACTER 


FUNCTION KEY AST 
SPECIFICATION BLOCK 
AST ADDRESS 
AST PARAMETER 
ACCESS MODE 
INPUT TOKEN STORAGE 
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Enable Input Simulation 

Simulates keystrokes, pointer motion, and pointer button transitions. 


Format 

SYS$QIO [efn] ,chan ,IO$-SETMODE ,[iosb] ,[astadr] 
,[astprm] ,p1 [,p2] [,p3] [,p4] [,p5] [,p6] 


Unique Parameters 

P1 — lOSC^QV^SIMULATE 

The function code that identifies what action the QIO performs. 

This parameter must be specified. 

P2 — address of ASCII text descriptor 

This parameter is a longword that points to a descriptor for the ASCII text 
to send to the current keyboard region. The maximum number of characters 
allowed in the text string is 32. If P2 is 0, no data is sent. 

This is an optional parameter. 

P3 — address of new pointer position 

This parameter is a longword that points to a two-longword array that 
defines a new pointer position. The first longword specifies the X coordinate 
of the new pointer position in pixels; the second longword specifies the Y 
coordinate. 

The following diagram shows the data structure that specifies the new 
pointer position. 


X position on physical screen 


Y position on physical screen 


Field 

Use 

X position on the physical screen 

Y position on the physical screen 

Specifies X coordinate in pixels 

Specifies Y coordinate in pixels 


This is an optional parameter. If P3 is 0, the pointer is not repositioned. 
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P4 — address of button simulation block 

This parameter is a longword that points to a button simulation block that 
specifies which pointer buttons are pressed or released. 

The following diagram shows a button simulation block. 


buttons to be pressed mask 


buttons to be released mask 


0 


0 


Field 

Buttons to be pressed mask 
Buttons to be released mask 


0 

0 


Use 

Mask of the buttons to be pressed 
Mask of the buttons to be released 


The pointer button definitions used in the masks 
are defined by the $QVBDEF macro. They 
consist of the following symbols: 


Symbol 

Meaning 

QV$M_BUTTON_ 

1 

Select button 

QV$M_BUTTON_ 

Button 2 

2 


QV$M_BUTTON_ 

Button 3 

3 


QV$M-BUTTON^ 

Button 4 

4 



This longword must be zero. 
This longword must be zero. 


This is an optional parameter. If P4 is zero, the pointer buttons are not 
modified. 


PS, P6 — must be 0 
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Example 

The example that follows shows typical programming for input simulation. 


5$: 


BSBW SET.CHARACTERISTICS 


BSBW SET^PERM_CURSOR 


SET UP SYSTEM 
CHARACTERISTICS 
SET UP NEW SYSTEMWIDE 
CURSOR PATTERN 


BSBW SET.MOUSEAST 
BSBW SIMULATE^INPUT 

$CLREF_S EFN=#2 

$WAITFR_S EFN=#2 

ERROR: $EXIT^S RO 


SET UP MOUSE REGION AST 
SIMULATE INPUT ON 
KEYBOARD 2. 

CLEAR EVENT FLAG #2 
WAIT FOR EVENT FLAG #2 


SIMULATE_INPUT: 

MOVL #IO$C^QV^SIMULATE,RO 
$qiOW^S CHAN=KBD.CHAN2.~ 

FUNC=#IO$_SETMODE.“ 

Pl=(RO),- 

P2=#SIM^ACK,- 

P3=#0 

BLBS R0,20$ 

BRW ERROR 

20$: RSB 


SIMUUTE KEYBOARD INPUT 
ON KEYBOARD CHANNEL 2 


NO ERROR IF SET 


SIM.ACK: 

.ASCID /This input SIMULATED on chan 2./ 
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Enable Keyboard Input 

Enables repeating character input ASTs for the process on the specified 
channel. 


Format 

SYS$QIO [efn] ,chan ,IO$-SETMODE ,[iosb] ,[astaclr] 
,[astprm] ,p1 ,p2 ,[p3J ,[p4] [,p5] [,p6] 


Unique Parameters 

PI — IO$C-OV^ENAKB 

The function code that identifies the action that the QIO performs. This 
parameter must be specified. 

To modify the action of the QIO, you can OR the IO$C_QV_ENAKB 
function code with one of the following optional function modifiers: 


Function Modifier 

Action 

IO$M_QV_CYCLE 

Removes the active keyboard from the head of the 
keyboard request list and places it at the end of the list 
(lowest priority). The next highest priority keyboard 
request then becomes the active keyboard request and a 
control AST is delivered on its behalf. 

IO$M_QV_DELETE 

Deletes the specified keyboard request. Any data 
contained in the type-ahead buffer is delivered to the 
specified AST address before the delete operation is 
executed. 

IO$M_QV_LAST 

Places the specified keyboard request last in the list. If 
IO$M_QV_LAST is not specified, the request is placed 
first in the list. If an outstanding keyboard request 
exists for the channel, it is updated to reflect the new 
priority. 

IO$M_QV_PURG_TAH 

Purges the type-ahead buffer of any keyboard request 
on this channel. 


P2 — address of a keystroke AST specification biock 

This parameter is a longword address that points to a keystroke AST 
specification block. This block specifies a user-supplied AST routine that 
is notified each time a keystroke occurs. 
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The following diagram shows the data structure that specifies a keystroke 
AST. 


AST service routine address 


AST parameter 


access mode 


input token address 


Field 

Use 

AST service routine address 

The address of the AST service routine is 0 if 
no AST routine is required. If no AST routine 
is specified, input is stored in the type-ahead 
buffer, and delivered either when an AST region 
is declared, or when a Get Next Input Token 
QIO is issued. 

AST parameter 

The user-defined AST parameter is delivered to 
the AST routine. The driver does not examine it. 

access mode 

The access mode at which to deliver the AST. It 
is maximized with the current access mode. 

input token address 

The input token address is the address of a 
longword that receives an input token when an 
AST routine is called. Word 0 of the longword 
contains token or character data. Values in 
the range of 0 to 255 map into the DIGITAL 
multinational character set. Values in the range 
of 256 to 512 map function keys into token 
values. Word 1 of the longword contains control 
information; bit 15 defines the status of a token 
(1 equals down, 0 equals up). By default an AST 
is only signaled on a down transition. 


The rest of the high-order word contains 
more control information that can be used 
to determine if the 1 Shift |, |Ctrl| , or I Lock | kevs 
are depressed. You can use these keys as 
meta-keys (keys used in combination). Bit 14 
corresponds to the 1 Shift | kev, bit 13 corresponds 
to the Ictrll key, and bit 12 corresponds to the 
|Lock| kev. When the bit is set, the kev is down. 


This parameter must be specified. 
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P3 — address of a keyboard request AST specification biock 

This parameter is a longword address that points to a keyboard request AST 
specification block. This block specifies a control AST routine that is notified 
when a keyboard request becomes active. A keyboard request becomes 
active when the active keyboard owner is deleted or a cycle request causes 
it to become active. No control AST is delivered when the new request is 
already active or the owning process issued the cycle request. 

The following diagram shows the data structure that specifies a keyboard 
request AST. 


AST service routine address 


AST parameter 


access mode 


Field 

Use 

AST service routine address 

The address of the AST service routine is 0 if 
no AST routine is required. If no AST routine 
is specified, input is stored in the type-ahead 
buffer, and delivered either when an AST region 
is declared, or when a Get Next Input Token 
QIO is issued. The type-ahead buffer holds 32 
input tokens or characters. 

AST parameter 

The user-defined AST parameter is delivered to 
the AST routine. The driver does not examine it. 

access mode 

The access mode at which to deliver the AST. It 
is maximized with the current access mode. 

0 

The fourth longword must be zero. 


This is an optional parameter. 

P4 — address of a keyboard characteristics biock 

This parameter is a longword address that points to a keyboard characteristics 
block. The keyboard characteristics block describes keyboard-related 
characteristics that are to be enabled or disabled for the keyboard region. 
The specified characteristics are enabled or disabled when the keyboard 
region becomes active. 
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The keyboard characteristics block is ignored if the keyboard region for this 
channel already exists. To modify the characteristics of an existing keyboard 
region, use the Modify Keyboard Characteristics QIO. 

The default characteristics are those specified in the systemwide char¬ 
acteristics block, which can be modified using the Modify Systemwide 
Characteristics QIO. The current systemwide characteristics are stored in the 
characteristics field of the QVB. 

The following diagram shows the data structure that specifies the keyboard 
characteristics block. 


enabled characteristics mask 


disabled characteristics mask 


keyclick volume 
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Field Use 

enabled characteristics mask The first longword is a mask of characteristics 

to be enabled. 

disabled characteristics mask The second longword is a mask of characteris¬ 

tics to be disabled. 

The keyboard characteristics, which are 
defined by the $QVBDEF macro, consist of 
the following bits: 


Characteristic 

Meaning 

QV$M_KEY_AUTORPT 

Key held down 
automatically 
repeats. Default 
is on. 

QV$M_KEY_KEYCLICK 

Keyclick 
sounds on 


each keystroke. 
Default is on. 

QV$M_KEY_UDF6 

Function keys 

F6 through 

FIO generate 
up/down 
transitions. 
Default is off. 

QV$M_KEY_UDF11 

Function keys 
Fll through 

FI4 generate 
up/down 
transitions. 
Default is off. 
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Field 

Use 



QV$M_KEY_UDF17 

Function keys 

FI 7 through 

F20 generate 
up/down 
transitions. 
Default is off. 


QV$M_KEY_UDHELPDO 

Function keys 
HELP and 



DO generate 
up/down 
transitions. 
Default is off. 


QV$M_KEY_UDE1 

Function keys 

El through 

E6 generate 
up/down 
transitions. 
Default is off. 


QV$M_KEY_UD ARROW 

Arrow keys 
generate 
up/down 
transitions. 
Default is off. 


QV$M_KEY_UDNUMKEY 

Numeric 
keypad keys 
generate 
up/down 
transitions. 
Default is off. 

keyclick volume 

The keyclick volume must be a value in the 
range of 1 to 8; 1 is loudest and 8 is softest. 

If a value of 0 is specified, the current system 
default keyclick volume is used. 

0 

The fourth longword must be 0. 


This is an optional parameter. 

P5, P6 — must be 0 
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Example 



The example that follow shows a t] 

^^pical assignment of two terminal 

channels, keyboard requests on those channels, and associated AST routines. 

P2 JLOCKl: 


AST SPECIFICATION BLOCK 1 

.LONG 

KBD.AST 

AST ADDRESS 

.LONG 

ACKl 

AST PARAMETER 

.LONG 

0 

AST DELIVERY MODE 

.LONG 

CHARACTER 

INPUT TOKEN 

ACKl: .ASCID 

/INPUT ACKNOWLEDGED CHANNEL 1/ 

P2.BL0CK2: 


AST SPECIFICATION BLOCK 2 

.LONG 

KBD^AST 


.LONG 

ACK2 


.LONG 

0 


.LONG 

CHARACTER 


ACK2: .ASCID 

/INPUT ACKNOWLEDGED CHANNEL 2/ 

P3JL0CK: 


CONTROL AST SPECIFICATION 



BLOCK 

.LONG 

CTL^AST 

CONTROL AST ADDRESS 

.LONG 

0 

AST PARAMETER 

.LONG 

0 

AST DELIVERY MODE 

.LONG 

0 

MUST BE ZERO 

SET^KBDAST: 



$ASSIGN_S DEVNAM=WS_DEVNAM,- 

; ASSIGN CHANNEL USING 


CHAN=KBD^CHAN2 

LOGICAL NAME AND 



CHANNEL NUMBER 

BLBS 

R0,5$ 

NO ERROR IF SET 

BRW 

ERROR 

ERROR 

20$: MOVL 

#I0$C_qV_ENAKB,R0 

ENABLE KEYBOARD AST 



REQUEST TO RO 

$qiow_s 

CHAN=KBD.CHAN2," 

ASSIGNED CHANNEL 


FUNC=#I0$_SETM0DE,- 

SET MODE QIO 


P1=(R0),- 

KEYBOARD AST REQUEST 


P2=#P23L0CK2.- 

USER AST ROUTINE 


P3=#P3_BL0CK 

CONTROL AST ROUTINE 

BLBS 

R0.30$ 

NO ERROR IF SET 
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BRW ERROR 


KBD.AST: 

FB^AST: 



.WORD 




PUSHL 

4(AP) 

; SEND ACKNOWLEDGMENT 


CALLS 

BLBS 

#1.G‘LIB$PUT_LINE 

RO, 10$ 

; MESSAGE 

5$: 

BRW 

ERROR 


10$: 

CMPW 

BNEQ 

#KEY$C_F5.CHARACTER 
20$ 

; WAS F5 TYPED? 


BSBW 

CYCLE_KBD 

; CYCLE THE KEYBOARD LIST 


BRB 

40$ 

; AND EXIT 

20$: 

PUSHAL 

CALLS 

BLBC 

DESC 

#1.G'LIB$PUT_LINE 

R0,5$ 

; SEND CHARACTER TYPED 


CMPB 

BNEQ 

#‘A/C/.CHARACTER 

30$ 

; WAS A "C" TYPED? 


BSBW 

BRB 

CYCLE_KBD 

40$ 

; CYCLE THE KEYBOARD LIST 

30$: 

CMPB 

BNEQ 

#‘A/F/,CHARACTER 

40$ 

; WAS AN "F" TYPED? 

40$: 

$SETEF. 

RET 

.S EFN=#2 

; YES, EXIT PROGRAM 


CTL.AST: 

.WORD 



PUSHAL 

CYCLE 

; SEND ACKNOWLEDGMENT 

CALLS 

#1.G"LIB$PUT_LINE 

; MESSAGE 

BLBS 

RO, 10$ 


5$: BRW 

10$: RET 

ERROR 
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Enable Keyboard Sound 

Enables a process to make a bell or keyclick sound on the LK201 keyboard. 


Format 

SYS$QIO [efn] ,chan ,IO$-SETMODE ,[iosb] ,[astadr] 
,[astprm] ,p 1 ,p2 [,p3] [,p4] [,p5] [,p6] 


Unique Parameters 

PI — IO$C-QV-SOUND 

The function code that identifies the action that the QIO performs. 

This parameter must be specified. 

P2 — symbolic name that denotes type of sound 

This parameter is a symbolic name that denotes the type of sound. The 
sound types, which are defined by the $QVBDEF macro, consist of the 
following bits: 


Characteristic 

Meaning 

QV$M_SOUND_BELL 

Sound bell. 

QV$M_SOUND_CLICK 

Sound keyclick. 


This parameter must be specified. 

P3 — value that specifies the sound volume 

This parameter specifies the sound volume, which must be a value in the 
range of 1 to 8; 1 is loudest and 8 is softest. If a value of 0 is indicated, the 
previously specified (that is, current) volume is used. 

This is an optional parameter. 

P4, PS, P6 — must be 0 
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Example 

The following example shows how the bell sound can be programmed. 


20$: MOVL #I0$C_QV_S0UND.R0 

$qiOW_S CHAN=SYS_CHAN1.- 

FUNC=#I0$_SETM0DE,- 
PI = (RO),- 
P2=#qV$M_S0UND_BELL 
BLBS R0,20$ 

BRW ERROR 


SOUND REqUEST TO RO 
ASSIGNED CHANNEL 
SET MODE qiO 
SOUND REqUEST 
SOUND TYPE IS BELL 
NO ERROR IF SET 
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Enable Pointer Movement 

Enables repeating pointer motion ASTs for the process on the specified 
channel. If this request has the highest priority for the specified rectangle, 
each pointer motion delivers an AST when the pointer cursor enters the 
specified area of the physical screen. 


Format 

SYS$QIO [efn] ,chan JO$^SETMODE ,[iosb] ,[astadr] 
,[astprm] ,p1 ,p2 ,[p3] ,[p4] [,p5] [,p6] 


Unique Parameters 

PI — IO$C-QV-MOUSEMOV 

The function code that identifies the action that the QIO performs. This 
parameter must be specified. 

To modify the action of the QIO, you can OR the IO$C_QV_MOUSEMOV 
function code with one of the following optional function modifiers: 


Function Modifier 

Action 

IO$M_QV_DELETE 

Deletes the specified pointer motion request. Any data 
contained in the type-ahead buffer is delivered to the specified 
AST address before the delete operation is executed. 

IO$M_QV_LAST 

Places the specified pointer motion request last in the list. If 
IO$M_-.QV__LAST is not specified, the request is placed first 
in the list. If an outstanding pointer motion request exists for 
the channel, it is updated to reflect the new priority. 


P2 — address of a pointer motion AST specification biock 

This parameter is a longword that points to a pointer motion AST 
specification block. This block specifies a user-supplied AST routine that 
is notified when pointer motion occurs. 

The following diagram shows the data structure that specifies a pointer 
motion AST. 
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AST service routine address 


AST parameter 


access mode 


address of new pointer cursor position 


AST service routine address The address of the AST service routine is 0 

if no AST routine is required. No buffering 
of data in the type-ahead buffer occurs for 
pointer motion ASTs. 

AST parameter The user-defined AST parameter is delivered 

to the AST routine. The driver does not 
examine it. 

access mode The access mode at which to deliver the AST. 

It is maximized with the current access mode. 

address of new pointer cursor The fourth longword contains the address 

position of a longword to receive the new pointer 

cursor position when the AST routine is 
called. (If your application does not need 
this information, specify a 0.) The low-order 
word receives the new X pixel location of the 
pointer cursor; the high-order word receives 
the new Y pixel location of the cursor. For 
screen pointers, X is in the range 0 through 
1023 with the lowest value denoting the left 
side of the screen; Y is in the range 0 through 
863 with the lowest value denoting the 
bottom of the screen. For tablet pointers, the 
range of X is defined in the qvh$w^tahlet^ 
width field of the QVSS block; the range of Y 
is defined in the qvb$w^tablet-Jieight field of 
the QVB block. 


This parameter must be specified. 

P3 — address of a pointer cursor exit AST specification biock 

This parameter is a longword that points to a pointer cursor exit AST 
specification block. This block specifies a user-supplied control AST routine 
that is notified when the pointer cursor exits from the rectangle specified by 

P6. 
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The following diagram show the data structure that specifies a pointer cursor 
exit AST. 


AST service routine address 


AST parameter 


access mode 


Field 

Use 

AST service routine address 

The address of the AST. service routine is 0 if 
no AST routine is required. 

AST parameter 

The user-defined AST parameter is delivered 
to the AST routine. The driver does not 
examine it. 

access mode 

The access mode at which to deliver the AST 
is maximized with the current access mode. 

0 

The fourth longword must be zero. 


This is an optional parameter. 

P4, P5 — must be 0 

P6 — address of a screen rectangle values block 

This parameter is a longword that points to a screen rectangle values block. 
This block defines a rectangle on the screen. 

The following diagram shows the data structure that specifies a screen 
rectangle. 
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Field 

Use 

MINX (left side value) 

MINY (bottom side value) 
MAXX (right side value) 

MAXY (top side value) 

Pixel value for left side of rectangle 

Pixel value for bottom side of rectangle 

Pixel value for right side of rectangle 

Pixel value for top side of rectangle 


This is an optional parameter. If you do not specify P6, a default rectangle 
that covers the entire screen is used. 


Description 

The QVSS and QDSS drivers track the pointer by moving the pointer cursor 
on the physical screen. In order to minimize desktop space required to 
manipulate the pointer, the driver updates the pointer cursor on the screen 
proportionally to the velocity at which the pointer is being moved on the 
desktop. The driver allows a process to enable a pointer motion notification 
request to signal pointer motion within a selected area of the physical screen. 
A token is passed to the specified AST address to indicate the new pointer 
cursor physical position. An input rectangle defines the area in which the 
application is interested in pointer motion. If rectangles for pointer motion 
requests for multiple channels (or processes) overlap, priority is given to the 
first rectangle on the list. 
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Example 

The following example shows how a pointer motion AST could be 
programmed. 


10$: MOVL #I0$C^QV_M0USEM0V.R0 ; ENABLE MOUSE MOTION 

$QI0W_S CHAN=MOUSE^CHAN,- ; REGION 

FUNC=#I0$_SETM0DE,- 
P1=(R0),~ 

P2=#M0USE_BL0CK,- 

P6=#M0USE„REGI0N 


BLBS R0,20$ 

BRW ERROR 

20$: RSB 

MOUSE JLOCK: 

.LONG MOUSE.AST 
.LONG MOUSE.ACK 
.LONG 0 
.LONG MOUSE.XY 


MOUSE^REGION: 

.LONG 400 
.LONG 400 
.LONG 800 
.LONG 800 


; NO ERROR IF SET 


MOUSE REGION AST 
SPECIFICATION BLOCK 
AST ADDRESS 
AST PARAMETER 
ACCESS MODE 

NEW MOUSE CURSOR POSITION 
STORAGE 

MOUSE REGION 
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Enable User Entry 

Assigns a control AST to each user entry in an optional graphics package 
entry list. The entry placed at the top of the list receives a control AST when 
a cycle request occurs, that is, an entry control AST request that includes the 
IO$M_Q\L.CYCLE function modifier. 


Format 

SYS$QIO [efn] ,chan ,IO$-SETMODE ,[iosb] .[astadr] 
,[astprm] ,p1 [,p2] ,p3 [,p4] [,p5] [,p6] 


Unique Parameters 

PI — IO$C-QV-ENAUSER 

The function code that identifies the action that the QIO performs. This 
parameter must be specified. 

To modify the action of the QIO, you can OR the IO$C_-QV_-ENABUSER 
function code with one of the following optional function modifiers: 


Function Modifier 

Action 

IO$M_QV_CYCLE 

Removes the active entry from the head of the entry list and 
places it at the end of the list (lowest priority). The next 
highest priority keyboard request then becomes the active 
keyboard request and a control AST is delivered on its behalf. 

IO$M_QV_DELETE 

Deletes the specified entry control request. Any data 
contained in the type-ahead buffer is delivered to the specified 
AST address before the delete operation is executed. 

IO$M_QV_LAST 

Places the specified entry control request last in the list. If 
10$M_QV_LAST is not specified, the request is placed first in 
the list. If an outstanding entry control request exists for the 
channel, it is updated to reflect the new priority. 


P2 — must be 0 

This parameter must be specified. 

P3 — address of an active entry AST specification biock 

This parameter is a longword that points to an active entry AST specification 
block. This block specifies a user-supplied control AST routine that is 
notified when this entry becomes active. 
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The following diagram shows the data structure that specifies an active entry 
AST. 


AST service routine address 


AST parameter 


access mode 


0 


Field 

Use 

AST service routine address 

The address of the AST service routine is 0 if 
no AST routine is required. 

AST parameter 

The user-defined AST parameter is delivered 
to the AST routine. The driver does not 


examine it. 

access mode 

The access mode at which to deliver the AST. 
It is maximized with the current access mode. 

0 

The fourth longword must be 0. 


This parameter must be specified. 

P4, PS, PS — must be 0 
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Get Keyboard Characteristics 

Obtains the keyboard characteristics for keyboard regions that already exist. 
The specified keyboard region is not changed and does not become the active 
keyboard region. 


Format 

SYS$QIO [efn] ,chan ,IO$-SENSEMODE ,[iosb] ,[astadr] 
,[astprm] ,p1 [,p2] [,p3] ,p4 [,p5] [,p6] 


Unique Parameters 

PI — IO$C-QV-GETKB-INFO 

The function code that identifies the action that the QIO performs. 

This parameter must be specified. 

P2, P3 — must be 0 

P4 — address of a keyboard characteristics biock 

This parameter is a longword that points to a keyboard characteristics block. 
This block receives the keyboard-related characteristics for this keyboard 
region. 

The following diagram shows the data structure into which the driver returns 
the keyboard characteristics. 


enabled characteristics mask 


disabled characteristics mask 


keyclick volume 


0 
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Field Use 

enabled characteristics mask The first longword is a mask of characteristics 

which are enabled. 

disabled characteristics mask The second longword is a mask of characteristics 

which are disabled. 


The keyboard characteristics, which are defined 
by the IQVBDEF macro, consist of the following 
bits: 


Characteristic 

Meaning 

QV$M_KEY_AUTORPT 

Key held down 
automatically repeats. 
Default is on. 

QV$M_KEY_KEYCLICK 

Keyclick sounds 
on each keystroke. 
Default is on. 

QV$M_KEY_UDF6 

Function keys F6 
through FIO generate 
up/down transitions. 
Default is off. 

QV$M_KEY_UDF11 

Function keys Fll 
through FI4 generate 
up/down transitions. 
Default is off. 

QV$M_KEY_UDF17 

Function keys FI 7 
through F20 generate 
up/down transitions. 
Default is off. 

QV$M_KEY_ 

UDHELPDO 

Function keys HELP 
and DO generate 
up/down transitions. 
Default is off. 

QV$M_KEY_UDE1 

Function keys El 
through E6 generate 
up/down transitions. 
Default is off. 

QV$M_KEY_ 

UDARROW 

Arrow keys generate 
up/down transitions. 
Default is off. 

QV$M_KEY_ 

UDNUMKEY 

Numeric keypad keys 
generate up/down 
transitions. Default is 
off. 
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Field 

Use 

keyclick volume 

The keyclick volume is a value in the range of 1 
to 8; 1 is loudest and 8 is softest. If a value of 0 
is returned, the current system default keyclick 
volume is used. 

0 

The fourth long word must be 0. 


This parameter must be specified. 

P5, P6 — must be 0 
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Get Next Input Token 

Intercepts the next input event for an entry on a list and returns it in the 
second longword of the I/O status block. 


Format 

SYS$QIO [efn] ,chan ,IO$—READVBLK ,iosb ,[astaclr] 
,[astprm] ,[p 1] ,p2 [,p3] [,p4] [,p5] [,p6] 


Unique Parameters 

PI — must be 0 

This parameter must be specified. 

P2 — symbolic name of list from which token is intercepted 

This parameter specifies the list on which the get function is performed. One 
of the following lists must be specified: 


List 

Function Performed 

IO$C_QV_ENABUTTON 

IO$C_QV_ENAKB 

IO$C_QV_MOUSEMOV 

Get next pointer button change. 

Get next token entered from the keyboard. 

Get next pointer motion. 


This parameter must be specified. 

P3, P4, PS, P6 — must be 0 


Description 

If the type-ahead buffer for that entry is empty, the QIO is held and then 
delivered as soon as the next token is obtained. If the type-ahead buffer 
is not empty, the first character in the type-ahead buffer is removed and 
delivered. Only one token is returned for each QIO issued. Regarding the 
decision as to where to deliver the next input token, this QIO preempts the 
AST routine for the entry. It is possible to queue several Get Next Input 
Token QIOs on a single entry. 

This QIO cannot be issued if the entry has an AST routine currently enabled. 
However, an AST routine can be enabled even though one or more of these 
QIOs may be outstanding on the entry. 
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Get Number of List Entries 

Allows you to obtain the number of AST entries contained in any of the 
following entry lists: 

• Keyboard entry list 

• Pointer button transition list 

• Pointer motion list 

• User entry list 


Format 

SYS$QIO [efn] ,chan ,IO$-SENSEMODE ,iosb ,[astadr] 
,[astprm] ,p1 ,p2 ,p3 [,p4] [,p5] [,p6] 


Unique Parameters 

PI — IO$C-QV-GET-ENTRIES 

This parameter must be specified. 

P2 — symbolic name of list from which you want to get entry count 

This parameter specifies the list on which the get function is performed. One 
of the following lists must be specified: 


List 

Function Performed 

IO$C_QV_ENAKB 

IO$C_QV_ENABUTTON 

IO$C_QV_MOUSEMOV 

IO$C_QV_ENAUSER 

Get number of entries in the keyboard entry list 

Get number of entries in the pointer button transition 
list 

Get number of entries in the pointer motion list 

Get number of entries in the user entry list 


This parameter must be specified. 

P3 — address of a longword to receive the number of entries 

This parameter must be specified. 

P4, PS, P6 — must be 0 
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Get System Information 

Returns the address of the system information block, which may be used by 
a process to obtain dynamic video-related information. The address of the 
system information block does not change. Therefore, a process need only 
obtain the address once and can reference it until the process terminates. 


Format 

SYS$QIO [efn] ,chan JO$^SENSEMODE ,[iosb] ,[astadr] 
,[astprm] ,p 1 ,p2 ,p3 [,p4] [,p5] [,p6] 


Unique Parameters 

PI — IO$C^QV^GETSYS 

The function code that identifies the action that the QIO performs. 

This parameter must be specified. 

P2 — address of quadword block 

This parameter is a longword that points to a quadword block to receive the 
address and length of the system information block. The structure is user 
read, kernel read/write. 

This parameter must be specified. 

P3, P4, PS, P6 — must be 0 


Description 

The system information block differs depending on whether you are using a 
QVSS system or a QDSS system. The system information block of the QVSS 
system is referred to as the QVB. The system information block of the QDSS 
system is referred to as the QDB. Both structures contain fields that hold 
information about video memory. Some of the information is static, such as 
the address of onscreen memory; other information is dynamic, such as the 
current pointer position. 

Appendix A contains a full illustration and explanation of the QVB. 
Appendix B contains a full illustration and explanation of the QDB. 
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Initialize Screen 

Initializes the screen to a known state. 


Format 

SYS$QIO [efn] ,chan ,IO$-SETMODE ,[iosb] Jastadr] 
,[astprm] ,p1 [,p2] [,p3] [,p4] lp5] [,p6] 


Unique Parameters 

PI — IO$C-QV-INITIALIZE function code 

The function code that identifies the action the QIO performs. 

This parameter must be specified. 

P2, P3, P4, PS, P6 — must be 0 


Description 

The Initialize Screen QIO initializes the workstation screen. You must 
initialize the screen whenever you initialize a windowing system that is 
going to use the QVSS or QDSS screen. The windowing system should issue 
this QIO only once, before it issues any other QIOs to the driver. 
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Load Compose Sequence Table 

Loads two-stroke and three-stroke compose sequence tables. 


Format 

SYS$QIO [efn] ,chan ,IO$-.SETMODE ,[iosb] ,[astadr] 
,[astprm] ,p 1 [,p2] [,p3] [,p4] [,p5] [,p6] 


Unique Parameters 

P1 — IO$C-QV-LOAD-COMPOSE-TABLE 

The function code that identifies the action that the QIO performs. This 
parameter must be specified. 

To modify the action of the QIO, you can OR the IO$C—QV_LOAD_ 
COMPOSE—TABLE function code with the following optional function 
modifier: 


Function Modifier 

Action 

IO$M_QV_LOAD_DEFAULT 

If the IO$M_QV_LOAD_DEFAULT modifier 
is specified, this table is the default table for 
the entire workstation. You should specify this 
modifier only once when you load the first table 
after you initialize the workstation. 


P2 — size of a two-stroke compose sequence table 

This parameter is a longword that contains the size (in bytes) of the two- 
stroke compose sequence table. 

This is an optional parameter. 

P3 — address of two-stroke compose sequence table 

This parameter is a longword that points to the two-stroke compose 
sequence table. For a complete description of the two-stroke compose 
sequence table, see Chapter 2. 

This is an optional parameter. 

P4 — size of three-stroke compose sequence table 

This parameter is a longword that contains the size (in bytes) of the three- 
stroke compose sequence table. 

This is an optional parameter. 
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P5 — address of the three-stroke compose sequence table 

This parameter is a longword that points to the three-stroke compose 
sequence table. For a complete description of the three-stroke compose 
sequence table, see Chapter 2. 

This is an optional parameter. 

P6 — must be 0 


Description 

If only one table is to be loaded, specify values of 0 for the parameters of the 
other table. 

A keyboard region has two tables associated with it for each type of compose 
sequence: the default table (taken from the workstation default), and a 
private table (if one has been loaded). 


Example 

The following example shows how to load a three-stroke compose sequence 
table. 
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SET.COMPOSES.TABLE: 


MOVE 

$QI0W_ 


#<I0$C_QV_L0AD_C0MP0SE_TABLE>, RO 


CHAN 
FUNC 
PI = 
P4 = 
P5 = 
R0,5$ 
ERROR 


= KBD^CHANl, - 
= #I0$^SETM0DE, - 
(RO). - 

#C0MP0SE3^TBL^LEN, - 
#C0MP0SE3.TBL 


CHANGE THE COMPOSE TABLE 


5$: 


BLBS 
BRW 
RSB 

VC$COMPOSE^KEYINIT 


C0MP0SE3^TBL 


three-stroke TABLE SIZE 
three-stroke TABLE ADDR 
NOT SET ON ERROR 


GENERATE AN 
EMPTY TABLE 
FILL THE TABLE HERE 


VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$COMPOSE_KEY 

VC$C0MP0SE_KEY 

VC$COMPOSE_KEY 

VC$COMPOSE_KEY 

VC$COMPOSE_KEY 


<‘a/A/>,<“a/"/>..<"xc4> 
<‘a/A/>.<‘a/7>. .<“xcl> 
<“a/A/>,<'a/*/>,.<*xc5> 
<“a/A/>,<'a/A/>,<0> 
<*a/A/>.<*a/E/>,,<*xc6> 
<“a/A/>, <''a/*/>,. <*xc2> 
<~a/A/>,<*a/_/>.,<“xaa> 


ORDER SENSITIVE 


VC$COMPOSE_KEYEND C0MP0SE3_TBL_LEN 


END THE TABLE 
AND DETERMINE ITS 
LENGTH 
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Load Keyboard Table 

Loads a keyboard table. 


Format 

SYS$QIO [efn] ,chan ,IO$-SETMODE ,[iosb] ,[astadr] 
,[astprm] ,p 1 ,p2 ,p3 [,p4] [,p5] [,p6] 


Unique Parameters 

PI — mC^QV^LOAD^KEY^TABLE 

The function code that identifies the action that the QIO performs. This 
parameter must be specified. 

To modify the action of the QIO, you can OR the IO$C-^QV-LOAD—KEY_ 
TABLE function code with the following optional function modifier: 


Function Modifier 

Action 

IO$M_QV_LOAD_DEFAULT 

If the IO$M_QV_LOAD_DEFAULT modifier 
is specified, this table is the default table for 
the entire workstation. You should specify this 
modifier only once when you load the first table 
after you initialize the workstation. 


P2 — size of keyboard table 

This parameter is a longword that contains the size (in bytes) of the keyboard 
table in bytes. 

This parameter must be specified. 

P3 — address of the keyboard table 

This parameter is a longword that points to the keyboard table. For a 
complete description of keyboard tables, see Chapter 2. 

This parameter must be specified. 

P4, PS, P6 — must be 0 
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Description 

Each window has two associated tables: the default table (taken from the 
workstation default), and a private table (if one has been loaded). 


Example 

The following example shows how to load a keyboard table. 


SETJRENCH.KB: 

MOVL #<IO$C^QV_LOAD_KEY.TABLE>, 

$QI0W^S CHAN = KBD_CHAN1, - 

FUNC = #I0$_SETM0DE, - 
PI = (RO), - 

P2 = #KB_LAYOUT^TBL^LEN, - 
P3 = #KB^LAYOUT_TBL 

BLBS R0.5$ 

BRW ERROR 

RSB 


RO 

; CHANGE THE KEYBOARD 
; LAYOUT 

; KEYBOARD TABLE SIZE 
; KEYBOARD TABLE 
; ADDRESS 
; NO ERROR IF SET 


5 $: 
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Modify Keyboard Characteristics 

Changes the keyboard characteristics for an existing keyboard region. 


Format 

SYS$QIO [efn] ,chan ,IO$-SETMODE ,[iosb] ,[astadr] 
,[astprm] ,p1 [,p2] [,p3] [,p4] [,p5] [,p6] 


Unique Parameters 

P1 — IO$C-QV-MODIFYKB 

The function code that identifies the action that the QIO performs. This 
parameter must be specified. 

To modify the action of the QIO, you can OR the IO$C_QVJMODIFYKB 
function code with the following optional function modifier: 


Function Modifier 

Action 

IO$M_QV_ACTIVE 

Removes the active keyboard from the head of the 
keyboard request list and places it at the end of the 
list (lowest priority). The keyboard region just modified 
becomes the active keyboard request and a control AST is 
delivered on its behalf. 


P2 — address of a keystroke AST specification biock 

This parameter is a longword that points to a keystroke AST specification 
block. This block specifies a user-supplied AST routine that is notified each 
time a keystroke occurs. 

The following diagram shows the data structure that specifies a keystroke 
AST. 


AST service routine address 


AST parameter 


access mode 


input token address 
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Field 

Use 

AST service routine address 

The address of the AST service routine is 0 if 
no AST routine is required. If no AST routine 
is specified, input is stored in the type-ahead 
buffer, and delivered either when an AST 
region is declared, or when a Get Next Input 
Token QIO is issued. The type-ahead buffer 
holds 32 input tokens or characters. 

AST parameter 

The user-defined AST parameter is delivered 
to the AST routine. The driver does not 
examine it. 

access mode 

The access mode at which to deliver the AST. 
It is maximized with the current access mode. 

input token address 

The input token address is the address of a 
longword that receives an input token when 
an AST routine is called. Word 0 of the 
longword contains token or character data. 
Values in the range of 0 to 255 map into the 
DIGITAL multinational character set. Values 
in the range of 256 to 512 map function keys 
into token values. Word 1 of the longword 
contains control information; bit 15 defines 
the status of a token (1 equals down, 0 equals 
up). By default an AST is only signaled on a 
down transition. 


This is an optional parameter. 

P3 — address of a keyboard request AST specification biock 

This parameter is a longword address that points to a keyboard request AST 
specification block. This block specifies a control AST routine that is notified 
when a keyboard request becomes active. A keyboard request becomes 
active when the active keyboard owner is deleted or a cycle request causes 
the keyboard request to become active. No control AST is delivered when 
the new request is already active or the owning process issued the cycle 
request. 
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The following diagram shows the data structure that specifies a keyboard 
request AST. 


AST service routine address 


AST parameter 


access mode 


0 


Field 

Use 

AST service routine address 

The address of the AST service routine is 0 if 
no AST routine is required. If no AST routine 
is specified, input is stored in the type-ahead 
buffer, and delivered either when an AST 
region is declared, or when a Get Next Input 
Token QIO is issued. The type-ahead buffer 
holds 32 input tokens or characters. 

AST parameter 

The user-defined AST parameter is delivered 
to the AST routine. The driver does not 


examine it. 

access mode 

The access mode at which to deliver the AST. 
It is maximized with the current access mode. 

0 

The fourth longword must be zero. 


This is an optional parameter. 

P4 — address of a keyboard characteristics biock 

This parameter is a longword address that points to a keyboard characteristics 
block. The keyboard characteristics block describes keyboard-related 
characteristics that are to be enabled or disabled for the keyboard region. 
The specified characteristics are enabled or disabled when the keyboard 
region becomes active. 

The default characteristics are those specified in the systemwide char¬ 
acteristics block, which can be modified using the Modify Systemwide 
Characteristics QIO. The current systemwide characteristics are stored in the 
characteristics field of the QVB. 
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The following diagram shows the data structure that specifies the keyboard 
characteristics. 


enabled characteristics mask 


disabled characteristics mask 


keyclick volume 


0 


Field Use 

enabled characteristics mask The first longword is a mask of characteristics to 

enable. 

disabled characteristics mask The second longword is a mask of characteristics 

to disable. 

The keyboard characteristics, which are defined 


by the $QVBDEF macro, 
bits: 

consist of the following 

Characteristic 

Meaning 

QV$M_KEY_AUTORPT 

Key held down 
automatically repeats. 
Default is on. 

QV$M_KEY_KEYCLICK 

Keyclick sounds 
on each keystroke. 
Default is on. 

QV$M_KEY_UDF6 

Function keys F6 
through FIO generate 
up/down transitions. 
Default is off. 

QV$M_KEY_UDF11 

Function keys Fll 
through FI4 generate 
up/down transitions. 
Default is off. 

QV$M_KEY_UDF17 

Function keys FI 7 
through F20 generate 
up/down transitions. 
Default is off. 
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Field 

Use 



QV$M_KEY_ 

UDHELPDO 

Function keys HELP 
and DO generate 
up/down transitions. 
Default is off. 


QV$M_KEY_UDE1 

Function keys El 
through E6 generate 
up/down transitions. 
Default is off. 


QV$M_KEY_ 

UDARROW 

Arrow keys generate 
up/down transitions. 
Default is off. 


QV$M_KEY_ 

UDNUMKEY 

Numeric keypad keys 
generate up/down 
transitions. Default is 
off. 

keyclick volume 

The keyclick volume must be a value in the range 
of 1 to 8; 1 is loudest and 8 is softest. If a value of 
0 is specified, the current system default keyclick 
volume is used. 

0 

The fourth longword must be 0. 


This is an optional parameter. 

PS, P6 — must be 0 
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Modify Systemwide Characteristics 

Changes the systemwide windowing characteristics. 


Format 

SYS$QIO [efn] ,chan ,IO$-SETMODE ,[iosb] ,[astaclr] 
,[astprm] ,p 1 [,p2] [,p3] [,p4] [,p5] [,p6] 


Unique Parameters 

PI — IO$C-QV-MODIFYSYS 

The function code that identifies the action that the QIO performs. 

This parameter must be specified. 

P2, P3 — must be 0 

P4 — address of a system characteristics block 

This parameter is a longword address that points to a system characteristics 
block. This block specifies the system-related characteristics that you want to 
enable or disable. 

The following diagram shows the data structure that specifies system 
characteristics. 


enabled characteristics mask 


disabled characteristics mask 


keyclick volume 


screen saver timeout value 
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Field 


Use 


enabled characteristics mask 
disabled characteristics mask 


The first longword is a mask of characteristics to 
enable. 

The second longword is a mask of characteristics 
to disable. 

The system characteristics, which are defined by 
the $QVBDEF macro, consist of the following bits: 


Characteristic 

QV$M_KEY^UTORPT 

QV$M_KEY^EYCLICK 

QV$M_KEY_UDF6 

QV$M_KEY_UDF11 

QV$M__KEY_UDF17 


Meaning 

Key held down 
automatically 
repeats. Default 
is on. 

Keyclick sounds 
on each keystroke. 
Default is on. 

Function keys 
F6 through FIO 
generate up/down 
transitions. Default 
is off. 

Function keys 
Fll through FI4 
generate up/down 
transitions. Default 
is off. 

Function keys 
FI 7 through F20 
generate up/down 
transitions. Default 
is off. 


QV$M_KEY_UDHELPDO Function keys 

HELP and DO 
generate up/down 
transitions. Default 
is off. 
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Field 


Use 


QV$M_KEY_UDE1 Function keys 

El through E6 
generate up/down 
transitions. Default 
is off. 

QV$M_KEY_UDARROW Arrow keys 

generate up/down 
transitions. Default 
is off. 

QV$M_KEY_UDNUMKEY Numeric keypad 

keys generate 
up/down 

transitions. Default 
is off. 

QV$M_SYS—SCRSAV Disable video output 

to monitor if no 
input activity 
occurs within the 
number of minutes 
specified in the 
fourth long word. 
Any keystroke, 
pointer button 
transition, or pointer 
motion resets the 
timer and reactivates 
a disabled screen. 
Default is on. 

keyclick volume The keyclick volume must be a value in the range 

of 1 to 8; 1 is loudest and 8 is softest. Default is 
3. 

screen saver timeout value The screen saver timeout value represents the 

number of minutes of inactivity that must elapse 
before the screen saver is activated. The value 
must be in the range of 1 to 1440. If a value 
of 0 is specified, then the timeout value is not 
changed. Default is 15. 


This is an optional parameter. 
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PS — address of a pointer characteristics biock 

This parameter is a longword address that points to a pointer characteristics 
block. This block specifies the pointer-related characteristics that you want to 
enable or disable. 

The following diagram shows the data structure that specifies pointer 
characteristics. 


enabled characteristics mask 


disabled characteristics mask 


0 


0 


Field 

Use 


enabled characteristics mask 

The first longword is a mask of characteristics to 
be enabled. 

disabled characteristics mask 

The second longword is 
to be disabled. 

a mask of characteristics 


The pointer characteristics, which are defined by 
the $QVBDEF macro, consist of the following bits: 


Characteristic 

Meaning 


QV$M_PTR_LEFT_ 

HAND 

Invert buttons on 
mouse or puck. 
(Buttons 1 and 3 are 
switched.) 


QV$M_PTR_INVERT_ 

STYLUS 

Invert buttons on 
stylus. (Buttons 1 and 
3 are switched.) 

0 

Must be 0 


0 

Must be 0 



This is an optional parameter. 

P6 — must be 0 
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Example 

The following example shows how the system windowing characteristics 
could be changed. 


SET_CHARACTERISTICS: 


MOVL 

#IO$C_QV_MODIFYSYS.RO ; 

CHANGE SYSTEM 

$QI0W_S 

CHAN=SYS_CHAN1.- ; 

FUNC=#I0$_SETM0DE,- 
PI = (RO),- 
P4 = #CHAR_BLOCK 

CHARACTERISTICS 

BLBS 

R0,10$ ; 

NO ERROR IF SET 

BRW 

ERROR 


CHAR.BLOCK: 


CHARACTERISTICS BLOCK 

.LONG 

<QV$M_SYS_AUTORPT! C1V$m1 

SYS^KEYCLICK> ; ENABLE 


> 

THESE CHARACTERISTICS 

.LONG 

<QV$M.SYS_UDF6!QV$M_SYS 

^UDARROW> ; DISABLE 



THESE CHARACTERISTICS 

.LONG 

5 • 

KEYCLICK VOLUME 

.LONG 

30 ; 

SCREEN SAVER TIMEOUT 
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Revert to Default Compose Table 

Reverts to the two-stroke or three-stroke default compose table. 


Format 

SYS$QIO [efn] ,chan ,IO$-SETMODE ,[iosb] .[astadr] 
,[astprm] ,p1 [,p2] [,p3] [,p4] [,p5] [,p6] 


Unique Parameters 

PI — IO$C-QV-USE-DEFAULT-TABLE 

The function code that identifies the action that the QIO performs. This 
parameter must be specified. 

To modify the action of the QIO, you can OR the IO$C^QVLUSE^ 
DEFAULT-_TABLE function code with one of the following optional function 
modifiers: 


Function Modifier 

Action 

IO$M_QV_COMPOSE2 

IO$M_QV_COMPOSE3 

Reverts to the two-stroke default compose table. 

Reverts to the three-stroke default compose table. 


P2, P3, P4, PS, P6 — must be 0 


Description 

This QIO also returns the space used by a private table (if one was loaded) 
to pool. 
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Revert to Default Keyboard Table 

Reverts to the default keyboard table. 


Format 

SYS$QIO [efn] ,chan ,IO$-SETMODE ,[iosb] ,[astadr] 
,[astprm] ,p 1 [,p2] [,p3] [,p4] [,p5] [,p6] 


Unique Parameters 

PI — IO$C-QV-USE-DEFAULT-TABLE!IO$M-QV-KEYS 

The function code that identifies the action that the QIO performs. The 
exclamation point (!) in the function code above indicates that you must OR 
the IO$C_QV_USE-_DEFAULT_TABLE function code and the IO$M_QV- 
KEYS function modifier to perform the QIO. 

This parameter must be specified. 

P2, P3, P4, PS, P6 — must be 0 


Description 

This QIO also returns the space used by a private table (if one was loaded) 
to pool. 
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Revert to Default Keyboard Table 

Reverts to the default keyboard table. 


Format 

SYS$QIO [efn] ,chan .IO$-SETMODE ,[iosb] ,[astadr] 
,[astprm] ,p1 [,p2] [,p3] [,p4] [,p5] [,p6] 

Unique Parameters 

P1 — IO$C-QV-USE-DEFAULT-TABLE ! IO$M-QV-KEYS 

The function code that identifies the action that the QIO performs. 

This parameter must be specified. 

P2, P3, P4, PS, P6 — must be 0 


Description 

This QIO also returns the space used by a private table (if one was loaded) 
to pool. 
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Chapter 4 

QDSS-Specific QIC Interface 


This chapter contains descriptions of the QIO calls that you can use only with the 
QDSS driver. The QIO descriptions appear in alphabetical order. The following list 
groups the QIOs by function. 


Functional Group 

QIO Name 

Controlling Color 

Set Color Characteristics 

Set Color Map Entries 

Defining Viewports 

Define Viewport Region 

Manipulating the DOP Queues 

Delete Deferred Queue 

Execute Deferred Queue 

Hold Viewport Activity 

Insert DOP 

Release Hold 

Resume Viewport Activity 

Start Request Queue 

Stop Request Queue 

Suspend Occluded Viewport Activity 

Suspend Viewport Activity 

Obtaining Information 

Get Color Map Entries 

Get Free DOPs 

Get Viewport ID 

Notify Deferred Queue Full 

Transferring Bitmaps 

Load Bitmap 

Read Bitmap 

Write Bitmap 


4.1 How to Use This Chapter 

Before attempting to call the QIOs described in this chapter, you should read 
Chapters 1 and 2 of this manual, and familiarize yourself with Appendixes A, B, 
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and H of this manual. Chapters 1 and 2 describe the general operation of the QIOs, 
the data types you pass to the driver through the PI to P6 parameters of several of 
the QIOs. Appendix H contains a complete description of the $QIO system service. 


4.1.1 QIO Description Format 

The QIO descriptions contained in this chapter follow a strict format. You should 

use them as reference material when you are coding a specific type of QIO. 

The following list notes the main headings in each QIO description and describes the 

type of information that appears there. 

• QIO name — Name of the QIO described. Appears in each description. 

• Overview — A brief description of the operation the QIO performs. Appears in 
each description. 

• Format — The format of the call to SYS$QIO. This format line contains the QIO 
function code you must pass to SYS$QIO to perform the desired operation. 

Arguments in brackets are optional arguments. In some programming languages, 
such as MACRO, you do not have to specify optional arguments; when you omit 
them, the assembler supplies a default value of 0. Some other programming 
languages, such as FORTRAN, do not allow you to omit optional arguments; you 
must pass a value of 0 for any argument you do not want to specify. Check the 
documentation for your programming language to see how it handles optional 
arguments. Appears in each description. 

• Unique Parameters — List of the information that you must pass to the driver 
through the PI to P6 parameters of $QIO. Each parameter description also tells 
you whether the parameter is required or optional. Appears in each description. 

• Description — Additional information about the operation of the QIO. Optional. 

• Example — Example of the QIO. Optional. 
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Define Viewport Region 

Creates or changes the update regions that comprise a viewport. 


Format 

SYS$QIO [efn] ,chan, IO$-SETMODE ,[iosb] ,[astadr] 
,[astprm] ,p1 ,p2 ,p3 ,p4 [,p5] [,p6] 


Unique Parameters 

PI — IO$C-QD-SET-VIEWPORT-REGIONS 

The function code that identifies the action the QIO performs. 

P2 — address of the update region definition buffer 

This is a longword that points to the buffer that describes the update regions 
that define the viewport. 

The following diagram shows the data structure that specifies each region. 


URD$W_Y_MIN 

URD$W_X_MIN 

URD$W_Y_MAX 

URD$W_X_MAX 

URD$W_Y_BASE 

URD$W_X_BASE 


The following list describes the contents of each field in the update region 
definition block. 
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Field 

Use 

URD$W_X_MIN 

Viewport-relative X coordinate of the lower left-hand corner 
of defined region (in pixels) 

URD$W_Y_MIN 

Viewport-relative Y coordinate of the lower left-hand comer 
of defined region (in pixels) 

URD$W_X_MAX 

Viewport-relative X coordinate of the upper right-hand corner 
of defined region (in pixels) 

URD$W_Y_MAX 

Viewport-relative Y coordinate of the upper right-hand corner 
of defined region (in pixels) 

URD$W_X_BASE 

Absolute X coordinate from lower left-hand corner (in pixels) 

URD$W_Y_BASE 

Absolute Y coordinate from lower left-hand corner (in pixels) 


This parameter must be specified. 

P3 — length of the update region definition buffer 

Specify the predefined constant URD$C—LENGTH multiplied by the number 
of update regions. 

This parameter must be specified. 

P4 — viewport ID 

The viewport ID of the viewport you are defining or changing. Use the Get 
Viewport ID QIO to obtain a unique viewport ID for any new viewport you 
want to define. 

This parameter must be specified. 

PS, P6 — must be 0 


Description 

The Define Viewport Region QIO function creates or modifies viewport 
update region definitions. The viewport that appears on the screen may be 
made up of a number of update regions. To access a viewport, you must 
call this function once. (A viewport must be made up of at least one update 
region.) If a viewport is made up of a number of regions, you make this 
call once, specifying an URD buffer (an array or record) that contains all the 
URDs. 

Before you make a Define Viewport Region QIO call, you must make a Stop 
Request Queue QIO function call. 
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A viewport management system uses this function to control the screen 
layout. When a drawing operation is executed, it is performed on each 
update region specified in the viewport definition. 
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Delete Deferred Queue Operation 

Deletes any entries in the specified deferred queue. 


Format 

SYS$QIO [efn] ,chan, IO$-SETMODE ,[iosb] ,[astadr] 
,[astprm] ,p 1 ,p2 [,p3] [,p4] [,p5] [,p6] 


Unique Parameters 

PI — IO$C-QD-DELETE-DEFERRED 

The function code that identifies the action the QIO performs. 

This parameter must be specified. 

P2 — viewportUd 

The viewport ID of the viewport associated with the deferred queue. The 
Get Viewport ID QIO returns the viewport ID during the creation of the 
viewport. 

This parameter must be specified. 

P3, P4, PS, P6 — must be 0 


Description 

The Delete Deferred Queue Operation QIO function deletes all operations on 
the deferred queue associated with the specified viewport. 

Typically, you use this call when you are popping an occluded viewport. 
You call it after an Execute Deferred Queue QIO has been executed for every 
update region previously stored in processor memory. 
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Execute Deferred Queue 

Processes any DOPs on the specified viewport's deferred queue. 


Format 

SYS$QIO [efn] ,chan, IO$-SETMODE ,[iosb] ,[astadr] 
,[astprm] ,p1 ,p2 [,p3] [,p4] [,p5] [,p6] 


Unique Parameters 

PI — IO$C-QD-.EXECUTE-DEFERRED 

The function code that identifies the action the QIO performs. 

This parameter must be specified. 

P2 — viewport^id 

The viewport ID of the targeted viewport. The Get Viewport ID QIO returns 
the viewport ID during the creation of the viewport. 

This parameter must be specified. 

P3, P4, PS, P6 — must be 0 


Description 

The Execute Deferred Queue QIO executes all operations on the deferred 
queue. All operations executed when the viewport was not accessible are 
replayed to the specified viewport buffer. 

The driver puts operations on the deferred queue when an operation is 
specified for a screen region that the QDSS hardware cannot currently access. 
The QDSS hardware cannot access a region when it is stored in processor 
memory. 

Operations on the deferred queue are executed into the currently defined set 
of region descriptors. If the buffer identifies visible screen locations, some 
unusual visual effects may be seen. 
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Get Color Map Entries 

Returns the values in the color map. 


Format 

SYS$QIO [efn] ,chan ,IO$-SENSEMODE ,[iosb] ,[astadr] 
,[astprni] ,p1 ,p2 ,p3 ,p4 [,p5] [,p6] 


Unique Parameters 

PI — IO$C-QD-GET-COLOR 

The function code that identifies the action the QIO performs. This 
parameter must be specified. 

To modify the action of the QIO, you can OR the IO$C_QD__GET—COLOR 
function code with one of the following optional function modifiers: 


Function Modifier Action 

IO$M^QD_INTENSITY Specify this value to get a map entry on an 

intensity system. 

IO$M_RESERVED_COLORS If the IO$M_RESERVED_COLORS modifier is 

specified, the starting color map entry (P4) is 
interpreted as the IO$C_QD_TWO_COLOR_ 
CURSOR (set two-color cursor) parameter. In this 
case, the buffer contains two map entries worth of 
data: two words for intensity systems, six words 
for color systems. 


P2 — address of a color buffer 

This is a longword pointing to a buffer to hold the returned entries of the 
color map. 

The size of the color buffer differs depending on whether you are using a 
color system or an intensity system. On a color system, the buffer must have 
an "RGB triple" for each map entry you wish to read. An "RGB triple" is 
made up of three word-long values, one for red, one for green, and one for 
blue. So, if you want to read five color map entries, the color buffer must be 
15 words long. 

On an intensity system, the buffer must have a single word-long value for 
each map entry you want to read. So, if you want to read five color map 
entries, the color buffer must be five words long. 
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Only the eight most significant bits are used for color definition. 

This parameter must be specified. 

P3 — length of the color buffer, in bytes 

On color systems, this must be a multiple of 6. On intensity systems this 
must be a multiple of 2. 

This parameter must be specified. 

P4 — starting color map entry 

The color map index to use for the first RGB or intensity value specified in 
the buffer. 

This parameter must be specified. 

PS, P6 — must be 0 


Description 

The Get Color Map Entries allows an application to read the color map, 
Color map information is stored in the QDB. You can access the QDB 
by issuing the Get System Information QIO. See Appendix B for a full 
description of the QDB. 
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Get Free DOPs 

Specifies how many DOPs must be on the specified return queue for request 
queue processing to continue. 


Format 

SYS$QIO [efn] ,chan ,IO$-SENSEMODE ,[iosb] ,[astadr] 
,[astprm] ,p 1 ,p2 ,p3 ,p4 [,p5] [,p6] 


Unique Parameters 

PI — IO$C-QD-GET-FREE-DOPS 

The function code that identifies the action the QIO performs. 

This parameter must be specified. 

P2 — number of DOPs 

The number of DOPs on the return queue that the driver should wait for 
before resuming request queue processing. 

This parameter must be specified. 

P3 — queue flag 

Flag specifying which return queue to wait for: a value of 0 indicates the 
normal (small DOP) queue; a value of 1 indicates the large DOP queue. 

This parameter must be specified. 

P4 — viewport—id 

The viewport ID of the targeted viewport. The Get Viewport ID QIO returns 
the viewport ID during the creation of the viewport. 

This parameter must be specified. 

PS, P6 — must be 0 


Description 

The Get Free DOPs QIO causes a process to wait until there are a specified 
number of drawing output primitives (DOPs) on the specified viewport 
return queue. 
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This function can be used to suspend operations until the driver returns a 
set of DOPs to the user. This way, the storage space for the DOPs can be 
reused. Note that you specify the number and size of the DOPs for which to 
wait. 

When this QIO completes and/or the associated AST is fired, the application 
allocates storage from the specified return queue (with the REMQUE 
instruction). In some rare instances, this QIO completes and nothing is 
on the return queue. When this occurs, reissue the QIO until the REMQUE 
succeeds. 
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Get Viewport ID 

Returns a unique viewport identifier, known as a viewport ID. 


Format 

SYS$QIO [efn] ,chan , IO$^SENSEMODE ,[iosb] ,[astadr] 
,[astprm] ,p1 ,p2 ,p3 [,p4] ip5] [,p6] 


Unique Parameters 

PI — IO$C^QD-GET^VIEWPORT-ID 

The function code that identifies the action the QIO performs. 

This parameter must be specified. 

P2 — address of the viewport ID buffer 

This is a longword pointing to a longword buffer into which the driver 
returns the viewport ID. 

This parameter must be specified. 

P3 — length of viewport ID buffer, in bytes 

The value of this parameter must be 4. 

P4 — address of alternate return queue 

By default (if this parameter is 0), each viewport is associated with two return 
queues. This optional parameter permits you to specify an address for an 
alternate return queue. For example, you may want to share return queues 
on a per-process basis instead of a per-viewport basis, or you may to want 
have a systemwide return queue. 
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The following diagram shows the data structure that specifies an alternate 
return queue. 


RET$L_RETURN_FLINK 


RET$L_RETURN_BLINK 


RET$L_RETURN_LARGE_FLINK 


RET$L_RETURN_LARGE_BLINK 


RET$W_LARGE_DOP_SIZE 


RET$W_SMALL_DOP_SIZE 


RET$I_APPLICATION-RESERVED 


The following list describes the contents of each field in the request queue 
definition. 


Field 

RET$L -RETURN-FLINK 
RET$L -RETURN-BLINK 

RET$L -RETURN-LARGE-FLINK 

RET$L -RETURN-LARGE-BLINK 

RET$ W-LARGE -DOP-SIZE 

RET$ W-SMALL -DOP-SIZE 

RET$L -APPLICATION-RESERVED 


Use 

Forward link for the ordinary return queue 

Backward link for the ordinary return 
queue 

Forward link for the large DOP return 
queue 

Backward link for the large DOP return 
queue 

Size of a DOP returned to the large DOP 
return queue 

Size of a DOP returned to the ordinary 
return queue 

A longword reserved for use by the 
application 


PS, P6 — must be 0 
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Description 

The Get Viewport ID QIO returns the unique viewport identifier. This 
identifier must be supplied as a parameter to several QIO functions. Note 
that this identifier is also the address of the DOP queue data structure (that 
contains the request queue and the return queue structures). 

You call this function at viewport creation time after you have an assigned 
channel. It must be called before any function that requires a viewport ID. 
It may be called only once for each channel; multiple calls result in multiple 
viewports 
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Hold Viewport Activity 

Stops activity on all viewports except the systemwide viewport. 


Format 

SYS$QIO [efn] ,chan, IO$-SETMODE ,[iosb] ,[astadr] 
,[astprm] ,p 1 [,p2] [,p3] [,p4] [,p5] [,p6] 


Unique Parameters 

PI — IO$C-QD-HOLD 

The function code that identifies the action the QIO performs. 
This parameter must be specified. 

P2, P3, P4, PS, P6 — must be 0 


Description 

The Hold Viewport Activity QIO function stops all activity on all viewports 
except the systemwide viewport. 

You use this function when moving a viewport or when implementing a hold 
screen function. 
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Insert DOP 

Inserts a DOP on the request queue of the specified viewport. Optionally, it 
notifies the caller of a request queue entry completion. 


Format 

SYS$QIO [efn] ,chan 

,IO$-QD-WRITE!IO$M-QD-INSERT-DOP.[iosb] 
,[astadr] ,[astprm] ,p 1 ,p2 ,p3 [,p4] [,p5] [,p6] 


Unique Parameters 

PI — address of the DOP entry 

A longword that points to the DOP entry for which you want completion 
notification. 

This parameter must be specified. 

P2 — length of the DOP entry 

A longword that contains the length of the DOP that you are inserting into 
the queue. 

This parameter must be specified. 

P3 — viewport—id 

The viewport ID of the targeted viewport. The Get Viewport ID QIO returns 
the viewport ID during the creation of the viewport. 

This parameter must be specified. 

P4, PS, PS — must be 0 


Description 


NOTE: The exclamation point (!) in the function code above indicates that 
you must OR IO$_QD_WRITE and IO$M_QD_INSERT_DOP to perform 
the Insert DOP QIO. 

The Insert DOP QIO permits you to enter a drawing operation primitive 
(DOP) on the request queue of a specified viewport. 
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If you specify the lOSB parameter, the system notifies your application when 
the request queue entry finishes executing. 

You can use the Insert DOP to synchronize drawing. If you insert a Stop 
Viewport Activity DOP on the queue (as opposed to issuing a Stop Request 
Queue QIO), you can guarantee that the DOPs inserted before the stop are 
executed. 

You should use this QIO only when your application requires notification 
that the request queue entry is finished executing. An INSQUE instruction or 
a UISDC$QUEUE_DOP routine is much more efficient. 
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Load Bitmap 

Makes available a bitmap for use by a subsequent text, patterned line, move, 
or fill operation. 


Format 

SYS$QIO [efn] ,chan ,IO$-SETMODE ,[iosb] ,[astadr] 
,[astprm] ,p1 ,p2 ,p3 ,p4 ,p5 ,p6 


Unique Parameters 

P1 — IO$C-QD-LOADJBITMAP 

The function code that identifies the action the QIO performs. This 
parameter must be specified. 

To modify the action of the QIO, you can OR the IO$C—QD-.-LOAD— 
BITMAP function code with the following optional function modifier: 


Function Modifier Action 

IO$M_QD_SYSTEM_WIDE Defines a bitmap that lasts for the life of the 

system. (By default, the bitmap is invalid after the 
channel it is originally returned on is deassigned.) 


P2 — address of the bitmap block 

A longword pointing to the area of processor memory that describes the 
desired bitmap. You may also specify a zero in this parameter to postpone 
dynamic loading of the bitmap — see the Description section for details. 

This parameter must be specified. 

P3 — length of the bitmap block, in bytes 

A longword that contains the length of the bitmap block in bytes. This value 
must be a multiple of 2. 

This parameter must be specified. 

P4 — address of a longword for the returned bitmap ID 

A longword into which the driver returns the bitmap ID. Subsequent drawing 
operations reference the loaded bitmap with the bitmap ID. All viewports 
and processes using the bitmap should refer to the bitmap with this bitmap 
ID. 

This parameter must be specified. 
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P5 — width of the bitmap, in bits 

A longword that contains the width of the bitmap, in bits. The maximum 
bitmap width you can specify is 1024. 

If the bitmap is a single bit per pixel, you must specify a multiple of 16 bits. 
This parameter must be specified. 

P6 — bits per pixei 

A longword that contains the number of bits per pixel. Currently 1 and 8 are 
supported. Specify the value 1 when a foreground and background color is 
sufficient (that is, for writing text). Specify the value 8 when you want the 
full use of color (that is, for natural images). 

This parameter must be specified. 


Description 

The Load Bitmap QIO makes available a bitmap that is used by a drawing 
operation. Bitmaps may specify the following: 

• Fonts 

• Line styles 

• Fill patterns 

• Images 

When you load a bitmap, you load it from VAX memory to offscreen 
memory. Once it is in offscreen memory, drawing operations can access 
it by using its bitmap ID. You need to load the bitmap only once each time 
the system is bootstrapped (unless you explicitly delete it with the Delete 
Bitmap DOP). 

Passing the Bitmap 

You must pass the bitmap to Load Bitmap in specific form because it is 
addressed using the X,Y coordinates rather than a single index. 

Bitmap storage is defined in blocks of video memory. The size of a bitmap 
block differs depending on whether you are using a single-plane or a 
multiplane image. 

• Single-plane bitmap blocks are 70 bits by 1024 bits. They can be thought 
of as 70 lines, each of which is 128 bytes wide. 
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• Multiplane bitmap blocks are 35 bits by 8180 bits. They can be thought 
of as 35 lines, each of which is 1024 bytes long. Each consecutive eight 
bits in a line describes one pixel (in 4-plane systems the high 4 bits are 
ignored). 

If a bitmap requires more room than can be provided by a single bitmap 
block, the bitmap must be stored in multiple blocks. This involves getting 
a separate bitmap ID for each block and keeping track of them in your 
application. 

Bitmaps are passed in blocks to the driver as follows: 

1. Each bitmap character (glyph) is stored in a rectangle within the bitmap. 
Glyphs are stored sequentially and may be packed to the bit; however, it 
is more efficient to start each character on a byte boundary. (The nature 
of multiplane bitmaps is such that this occurs naturally.) 

2. If the total width of all glyphs exceeds the bitmap block limit, you must 
use another bitmap block, which you load separately. 

3. Any unused portion of a single-plane bitmap line must be padded with 
zeros to the nearest word boundary. (Again, the nature of multiplane 
bitmaps is such that this occurs naturally.) 

Figure 4-1 following is an example of a large font that uses more than one 
single-plane bitmap block. Each character is 32 bits high by 40 bits wide. 
(To include the lowercase letters, you would have to use yet another bitmap 
block.) Notice that the characters are aligned on word boundaries for better 
performance. If space is a greater consideration than performance, you 
could pack the characters to fit more in each bitmap block. Remember, your 
application must load each block separately and keep track of the different 
bitmap IDs. 
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{ 


Figure 4-1 Large Font Defined Across Bitmap Blocks 

1024 bits wide 



ZK 5477 86 



Loading the Bitmap 

There are two ways to use Load Bitmap: 

• One causes the bitmap to be copied from the user's buffer into a buffer 
maintained by the driver. When your application accesses the bitmap, it 
is copied from the driver-maintained buffer into offscreen memory. 

• The other creates a handle (identifier) for the bitmap, but relies on 
the application to supply the bitmap when it is accessed. This second 
method saves space by not loading a bitmap into offscreen memory until 
an application accesses it. 
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To have the driver maintain the bitmap — Specify the address of the 
bitmap in process memory as the bitmap address parameter. To access the 
bitmap in a subsequent DOP, load the bitmap.^ID field of the DOP Common 
block with the bitmap ID returned by Load Bitmap. The system handles the 
storage of this bitmap. 

When the system manages bitmap storage, it uses the bitmap glyph as a 
backing store address if it has to swap the bitmap out of offscreen memory. 
That is, when the bitmap is accessed, the system uses the address in the 
bitmap glyph to swap the bitmap back into offscreen memory. 

To dynamically load a bitmap — Specify zero as the bitmap address 
parameter, but still specify the correct length, width, and bits-per-pixel. To 
access the bitmap in a subsequent DOP, load the bitmap JD field of the 
DOP Common block with the bitmap ID returned by Load Bitmap and load 
the bitmap—glyph field of the DOP Common block with the address of the 
bitmap in processor memory. 

When you specify a bitmap address of 0 and put the actual address in the 
bitmap—glyph field, you save system resources. The bitmap is not loaded 
until it is accessed, and the application, not the system, is responsible for 
saving the bitmap (when it is swapped out, it is unknown by the system). 

Systemwide Bitmaps 

Usually, a bitmap is defined as temporary. That is, the bitmap ID associated 
with it is not valid once you deassign the channel on which it was loaded. 
To define a bitmap to last for the life of the system, issue this QIO using the 
IO$M-QD-SYSTEM_WIDE function modifier. 
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Notify Deferred Queue Full 

Notifies the application when a deferred queue is full. 


Format 

SYS$QIO [efn] ,chan ,IO-$SENSEMODE ,[iosb] ,[astadr] 
.[astprm] ,p1 ,p2 ,p3 [,p4] [,p5] [,p6] 


Unique Parameters 

PI — IO$C-QD-DEFERRED-HOLD 

The function code that identifies the action the QIO performs. 

This parameter must be specified. 

P2 — waiting period 

A longword that contains the number of 80-millisecond intervals to wait after 
the queue is full before notification. (One second is equivalent to seventeen 
80-millisecond intervals.) 

This parameter must be specified. 

P3 — viewport^id 

The viewport ID of the targeted viewport. The Get Viewport ID QIO returns 
the viewport ID during the creation of the viewport. 

This parameter must be specified. 

P4, PS, P6 — must be 0 


Description 

The Notify Deferred Queue Full QIO notifies an application when the 
deferred queue is full. The number of drawing operations that can be 
deferred for any one viewport is limited so that the system resources cannot 
be consumed by that viewport. When an application is notified of a full 
queue, it can load the viewport into memory, execute the deferred operations 
and delete the deferred queue — freeing up memory. If necessary, the 
application may then put the viewport back in a deferred state. 

Notification may be performed using the QIO AST, an event flag, or a wait. 
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Read Bitmap 


Copies data from video memory to a user-specified buffer in VAX memory 
and performs bitmap-to-bitmap transfers. 

Format 


SYS$QIO 

[efn] ,chan ,IO$—QDREAD ,[iosb] ,[astadr] ,[astprm] 
,p1 ,p2 ,[p3] ,p4 ,p5 [,p6] 


Unique Parameters 

PI — buffer address 

The address of the buffer in VAX memory into which the driver should copy 
the bitmap. This buffer must be large enough to hold the bitmap specified 
by P4. For a bitmap-to-bitmap transfer, specify a 0 in this parameter. 

This parameter must be specified. 

P2 — buffer length 

A longword that contains the length of the buffer specified by PI, in bytes. 

P3 — must be 0 

P4 — transfer parameter block 

The transfer parameter block (TPB) describes the bitmap to be read into VAX 
memory. The TPB contains: 

• The coordinates for the lower left-hand corner of the bitmap 

• The height and width of the bitmap 

• A predefined constant indicating the type of transfer 

• For a bitmap-to-bitmap transfer, the coordinates for the lower left-hand 
comer of the target bitmap 
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The following diagram shows the data structure that specifies the transfer 
parameters. 


TPB$W_X_SOURCE 

TPB$B_SIZE TPB$B_TYPE 

TPB$W_WIDTH 

TPB$W_Y_SOURCE 

TPB$W_X_TARGET 

TPB$W_HEIGHT 

TPB$W_X_TARGET_VEC1 

TPB$W_Y_TARGET 

TPB$W_L _TARGET_VEC1 

TPB$W_Y_TARGET_VEC1 

TPB$W_Y_TARGET_VEC2 

TPB$W_X_TARGET_VEC2 


TPB$W_L_TARGET_VEC2 


The following list describes the contents of each field in the Transfer 
Parameter block. 


Field 

Use 

TPB$B_TYPE 

Type of transfer being performed, either bitmap- 
to-processor (DTP) or bitmap-to-bitmap (BTB); use 
the constants defined below to load this field 

TPB$B_SIZE 

Reserved to DIGITAL 

TPB$W_X_SOURCE 

X coordinate of lower left-hand corner of source 
bitmap 

TPB$W_Y_SOURCE 

Y coordinate of lower left-hand corner of source 
bitmap 

TPB$W_WIDTH 

Width of source bitmap 

TPB$W_HEIGHT 

Height of source bitmap 

TPB$W_X_TARGET 

X coordinate of lower left-hand corner of target 
bitmap (only specified for bitmap-to-bitmap 
transfer) 

TPB$W_Y_TARGET 

Y coordinate of lower left-hand corner of target 
bitmap (only specified for bitmap-to-bitmap 
transfer) 

TPB$W_X_TARGET_VEC1 

Reserved to DIGITAL 

TPB$W_Y_TARGET_VEC1 

Reserved to DIGITAL 

TPB$W_L_TARGET_VEC1 

Reserved to DIGITAL 
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Field 

Use 

TPB$W_X_TARGET_VEC2 

Reserved to DIGITAL 

TPB$W_Y_TARGET_VEC2 

Reserved to DIGITAL 

TPB$W_L _TARGET_VEC2 

Reserved to DIGITAL 
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Constants — The following constants are defined in conjunction with the TPB. 


Constant 

Value 

TPB$C_BITMAP_XFR 

Used to specify a bitmap-to-bitmap transfer 

TPB$C_SOURCE_ONLY 

Used to specify a BTP or PTB transfer 

TPB$C_SOURCE_LENGTH 

Structure length for BTP or PTB transfers 

TPB$C_BITMAP_XFR_LENGTH 

Structure length for a bitmap-to-bitmap 
transfer 

TPB$C_LENGTH 

Full length of TPB structure. 


This parameter must be specified. 

PS — TPB length 

A longword that contains the length of the transfer parameter block specified 
in P4, in bytes. 

This parameter must be specified. 

P6 — must be 0 


Description 

The Read Bitmap QIO reads data from the QDSS video memory into a 
specified buffer in VAX memory. This function transfers all available planes 
of memory at once. If this operation is to affect more than one viewport, it 
must be preceded by a Stop Request Queue QIO. 

You can also use it to perform bitmap-to-bitmap transfers. In a bitmap-to- 
bitmap transfer, you specify a source and target location in the TPB and omit 
the processor buffer. 
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Release Hold 

Releases all viewports from the hold state. 

Format 

SYS$QIO [efn] ,chan, IO$-SETMODE ,[iosb] .[astadr] 
,[astprm] ,p1 [,p2] [,p3] [,p4] [,p5] [,p6] 

Unique Parameters 

P1 — lOSC^QD^NOHOLD 

The function code that identifies the action the QIO performs. 

This parameter must be specified. 

P2, P3, P4, PS, P6 — must be 0 

Description 

The Release Hold QIO function releases viewports from the hold state. 

A viewport is put into the hold state when the Hold Viewport Activity QIO 
is issued. All viewports, except the systemwide viewport, are affected by a 
Hold Viewport Activity QIO. 

A count of the number of hold requests is maintained. When the number of 
release hold requests equals the number of hold requests, the driver releases 
the screen. 
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Resume Viewport Activity 

Resumes activity in a previously suspended viewport. 


Format 

SYS$QIO [efn] ,chan , IO$-SETMODE ,[iosb] ,[astadr] 
,[astprm] ,p1 ,p2 [,p3] [,p4] [,p5] [,p6] 


Unique Parameters 

PI — IO$C-OD-RESUME-VP 

The function code that identifies the action the QIO performs. 

This parameter must be specified. 

P2 — viewport—id 

The viewport ID of the targeted viewport. This ID is returned by the Get 
Viewport ID during the creation of the viewport. 

This parameter must be specified. 

P3, P4, PS, P6 — must be 0 


Description 

The Resume Viewport Activity QIO function resumes activity on a viewport 
that had previously been suspended using the Suspend Viewport Activity 
QIO function. 
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Set Color Characteristics 

Identifies a system as either color or intensity based. 


Format 

SYSSQIO [efn] ,chan ,IO$-SETMODE ,[iosb] ,[astadr] 
,[astprm] ,p 1 ,p2 [,p3] [,p4] [,p5] [,p6] 


Unique Parameters 

P1 — IO$C-QD-COLOR-CHAR 

The function code that identifies the action the QIO performs. 

This parameter must be specified. 

P2 — system flag 

A longword that indicates whether the system is color or intensity based. A 
value of 0 indicates a color (RGB) system. A value of 1 indicates an intensity 
(monochrome) system. 

This parameter must be specified. 

P3, P4, PS, P6 — must be 0 


Description 

The Set Color Characteristics QIO identifies a system as either color or 
intensity based. Your application must use this call to inform the driver 
about which type of color system it is using. Once this is specified, the driver 
only accepts Set Color Map Entries QIO requests that match this setting. It 
rejects all other Set Color Map Entries QIOs. 







July 1987 


QDSS-Specific QIO Interface 4-3i 
Set Color Map Entries 


Set Color Map Entries 

Defines (or alters) the color map. 


Format 

SYS$QIO [efn] ,chan ,IO$-SETMODE ,[iosb] ,[astadr] 
,[astprm] ,p1 ,p2 ,p3 ,p4 ,p5 [,p6] 


Unique Parameters 

PI — IO$C^QD^SET^COLOR 

The function code that identifies the action the QIO performs. This 
parameter must be specified. 

To modify the action of the QIO, you can OR the IO$C_QD_SET_COLOR 
function code with one of the following optional function modifiers: 


Function Modifier Action 

IO$M_QD_INTENSITY Specify this modifier to set a map entry on an 

intensity system. 

IO$M_RESERVED_COLORS If the IO$M_RESERVED_COLORS modifier is 

specified, the starting color map entry (P4) is inter¬ 
preted as the IO$C_QD_TWO_COLOR_CURSOR 
(set two-color cursor) parameter. In this case, the 
buffer must contain two map entries worth of data: 
two words for intensity systems, six words for color 
systems. 


P2 — address of the color buffer 

The color buffer differs depending on whether you are using a color system 
or an intensity system. 

On a color system, the buffer must have an "RGB triple" for each map entry 
you wish to set. An "RGB triple" is made up of three word-long values, one 
for red, one for green, and one for blue. So, if you want to set five color map 
entries, the color buffer must be 15 words long. 

On an intensity system, the buffer must have a single word-long value for 
each map entry you want to set. So, if you want to set five color map entries, 
the color buffer must be five words long. 

Only the eight most significant bits are used for color definition. 
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This parameter must be specified. 

P3 — length of the color buffer, In bytes 

A longword that contains the length of the color buffer, in bytes. On color 
systems, this must be a multiple of 6. On intensity systems this must be a 
multiple of 2. 

This parameter must be specified. 

P4 — starting color map entry 

A longword that contains the color map index to use for the first RGB or 
intensity value specified in the buffer. 

This parameter must be specified. 

PS — color map selection 

Must be 0. 

P6 — must be 0 


Description 

The Set Color Map Entries allows an application to define or alter the color 
map. Color map information is stored in the QDB. You can access the 
QDB by issuing the Get System Information QIO. See Appendix B for a full 
description of the QDB. 
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Start Request Queue 

Starts the processing of any packets on the request queue. 


Format 

SYS$QIO [efn] ,chan, IO$-SETMODE ,[iosb] .[astadr] 
,[astprm] ,p 1 ,p2 [,p3] [,p4] [,p5] [,p6] 


Unique Parameters 

PI — IO$C-QD-START 

The function code that identifies the action the QIO performs. 

This parameter must be specified. 

P2 — viewportJid 

The viewport ID of the targeted viewport. The Get Viewport ID QIO returns 
the viewport ID during the creation of the viewport. 

This parameter must be specified. 

P3, P4, PS, P6 — must be 0 


Description 

The Start Request Queue QIO function starts (or restarts) the processing of 
packets on the request queue of the specified viewport. 

Typically, your application makes this call after the queue has been stopped 
with the Stop Request Queue QIO function or after initial viewport creation. 
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Stop Request Queue 

Stops the processing of any packets on the request queue. 


Format 

SYS$QIO [efn] ,chan, IO$-SETMODE ,[iosb] ,[astadr] 
,[astprm] ,p1 ,p2 [,p3] [,p4] [,p5] [,p6] 


Unique Parameters 

PI — IO$C-QD-STOP 

The function code that identifies the action the QIO performs. 

This parameter must be specified. 

P2 — viewport—id 

The viewport ID of the targeted viewport. The Get Viewport ID QIO returns 
the viewport ID during the creation of the viewport. 

This parameter must be specified. 

P3, P4, PS, P6 — must be 0 


Description 

The Stop Request Queue QIO stops all processing on the request queue of 
the specified viewport in order to give the calling process complete control 
over the viewport bitmap. Stopping a viewport's request queue insures that 
no other processes can modify the bitmap of the stopped viewport. 

A viewport management task typically uses this function when changing 
the position of any viewport in the system (using the Set Viewport Region 
QIO function). An application can also use it to freeze the screen for printing 
displayed data. 

Once the Stop Request Queue QIO is invoked, no further commands can 
be executed from the request queue unless the request queue is explicitly 
restarted with the Start Request Queue QIO. 

A Stop Request Queue QIO differs from a Suspend Viewport Activity QIO 
in that it waits for currently processing DOPs to complete before returning 
control. 
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Suspend Occluded Viewport Activity 

Suspends all operations to a specified (occluded) viewport when certain 
operations are requested. 


Format 

SYS$QIO [efn] ,chan ,IO$-SENSEMODE ,[iosb] ,[astadr] 
,[astprm] ,p 1 ,p2 [,p3] [,p4] [,p5] [,p6] 


Unique Parameters 

PI — IO$C-OD-OCCLUDED-SUSPEND 

The function code that identifies the action the QIO performs. 

This parameter must be specified. 

P2 — viewport^id 

The viewport ID of the targeted viewport. The Get Viewport ID QIO returns 
the viewport ID during the creation of the viewport. 

This parameter must be specified. 

P3, P4, PS, P6 — must be 0 


Description 

The Suspend Occluded Viewport Activity QIO suspends operations to an 
occluded viewport when a DOP that the driver cannot process is executed. 

Operations that the driver cannot perform on occluded viewports are 
typically Scroll, Move Area, and Move/Rotate operations in which the 
source is not a bitmap ID. 

The application must handle the operation and then issue a Resume 
Viewport Activity QIO to continue request queue processing. You may 
handle the operation in the associated AST. The address of the DOP is 
returned in the second longword of the lOSB block. For example, if a Scroll 
is attempted on an occluded viewport, the driver detects the condition and 
fires the AST associated with Suspend Occluded Viewport Activity QIO. The 
AST uses the DOP address returned in the lOSB to determine what action 
to take and issues a Resume Viewport Activity QIO for the viewport when it 
completes. 
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Suspend Viewport Activity 

Suspends activity in a specified viewport. 


Format 

SYS$QIO [efn] ,chan, IO$-SETMODE ,[iosb] ,[astadr] 
,[astprm] ,p 1 ,p2 [,p3] [,p4] [,p5] [,p6] 


Unique Parameters 

PI — IO$C-QD-SUSPEND-VP 

The function code that identifies the action the QIO performs. 

This parameter must be specified, 

P2 — viewport-^id 

The viewport ID of the targeted viewport. The Get Viewport ID QIO returns 
the viewport ID during the creation of the viewport. 

This parameter must be specified. 

P3, P4, PS, P6 — must be 0 


Description 

The Suspend Viewport Activity QIO function suspends all activity on a 
specified viewport. 

Typically, this call is used to synchronize drawing operations. When any 
necessary operations are completed, you can resume activity on the viewport 
by making a call to the Resume Viewport Activity QIO function. 

A Suspend Viewport Activity QIO differs from a Stop Request Queue QIO 
in that it does not wait for currently processing DOPs to complete before 
returning control. 
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Write Bitmap 

Writes data from a user-specified buffer in VAX memory to a bitmap in video 
memory and also performs bitmap-to-bitmap transfers. 


Format 

SYS$QIO [efn] ,chan ,IO$-QDWRITE ,[iosb] ,[astadr] 
,[astprm] ,p1 ,p2 ,[p3] ,p4 ,p5 [,p6] 


Unique Parameters 

P1 — buffer address 

The address of the buffer in VAX memory from which the bitmap is written. 
This buffer must be large enough to hold the bitmap specified in the transfer 
parameter block (P4). In a bitmap-to-bitmap transfer, specify a zero in this 
parameter. 

This parameter must be specified. 

P2 — buffer length 

A longword that contains the length of the buffer specified in PI, in bytes. 
This parameter must be specified. 

P3 — must be 0 

P4 — transfer parameter block 

The transfer parameter block (TPB) that describes the bitmap which is to be 
written into video memory. The TPB contains: 

• The coordinates for the lower left-hand corner of the bitmap 

• The height and width of the bitmap 

• A predefined constant indicating the type of transfer 

• For bitmap-to-bitmap transfer, the coordinates for the lower left-hand 
comer of the target bitmap 

The following diagram shows the data structure that specifies transfer 
parameters. 





November 1986 


4-38 QDSS-Specific QIO Interface 

Write Bitmap 


TPB$W_X_SOURCE 

TPB$B_SIZE TPB$B_TYPE 

TPB$W_WIDTH 

TPB$W_Y_SOURCE 

TPB$W_X_TARGET 

TPB$W_HEIGHT 

TPB$W_X_TARGET_VEC1 

TPB$W_Y_TARGET 

TPB$W_L _TARGET_VEC1 

TPB$W_Y_TARGET_VEC1 

TPB$W_Y_TARGET_VEC2 

TPB$W_X_TARGET_VEC2 


TPB$W_L _TARGET_VEC2 


The following list describes the contents of each field in the Transfer 
Parameter block. 


Field 

Use 

TPB$B_TYPE 

Type of transfer being performed, either processor- 
to-bitmap (PTB) or bitmap-to-bitmap (BTB) Use the 
constants defined below to load this field 

TPB$B_SIZE 

Reserved to DIGITAL 

TPB$W_X_SOURCE 

X coordinate of lower left-hand corner of source 
bitmap 

TPB$W_Y_SOURCE 

Y coordinate of lower left-hand corner of source 
bitmap 

TPB$W_WIDTH 

Width of source bitmap 

TPB$W_HEIGHT 

Height of source bitmap 

TPB$W_X-TARGET 

X coordinate of lower left-hand corner of target 
bitmap (only specified for bitmap-to-bitmap transfer) 

TPB$W_Y_TARGET 

Y coordinate of lower left-hand comer of target 
bitmap (only specified for bitmap-to-bitmap transfer) 

TPB$W_X_TARGET_VEC1 

Reserved to DIGITAL 

TPB$W_Y_TARGET_VEC1 

Reserved to DIGITAL 

TPB$W_L -TARGET-VECl 

Reserved to DIGITAL 

TPB$W_X_TARGET_VEC2 

Reserved to DIGITAL 

TPB$W_Y_TARGET_VEC2 

Reserved to DIGITAL 

TPB$W_L _TARGET_VEC2 

Reserved to DIGITAL 
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Constants — The following constants 

are defined in conjunction with the TPB. 

Constant 

Value 

TPB$C_BITMAP_XFR 

TPB$C_SOURCE_ONLY 

TPB$C_SOURCE_LENGTH 

TPB$C_BITMAP_XFR_LENGTH 

TPB$C_LENGTH 

Used to specify a bitmap-to-bitmap transfer. 
Used to specify a BTP or PTB transfer. 

Structure length for BTP or PTB transfers. 

Structure length for a bitmap-to-bitmap 
transfer. 

Full length of TPB structure. 

P5 — TPB length 


A longword that contains the length of the transfer parameter block specified 
in P4, in bytes. 

P6 — must be 0 


Description 

The Write Bitmap QIO writes data from a specified buffer in VAX memory to 
QDSS video memory. This function transfers all available planes of memory 
at once. If this operation is to affect more than one viewport, it must be 
preceded by a Stop Request Queue QIO. 

Your application may also use it to perform bitmap-to-bitmap transfers. In 
a bitmap-to-bitmap transfer, you specify a source and target location in the 
TPB and omit the processor buffer. 
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Using Drawing Operation Primitives 


This chapter describes: 

• What drawing operation primitives (DOPs) are 

• How to perform drawing operations to the screen using DOPs 

• How to perform window management operations using DOPs 

• How to use features of the UISDC interface when implementing DOPs 


5.1 What Are DOPs? 

Drawing operation primitives (referred to as DOPs) are data structures created by 
your application that contain information the QDSS hardware uses to perform 
drawing operations to the screen. (Some DOPs are also used to perform window 
management tasks; for example, to suspend and resume request queue activity on a 
specific viewport.) 

DOPs provide a fast and simple way of performing basic drawing operations. The 
following is a list of the drawing operations you can perform using DOPs: 

• Draw a simple line, a complex line, a series of lines, or a polygon 

• Draw a point, or a series of points 

• Draw a filled polygon using a bitmap pattern 

• Fill points using an associated bitmap pattern 

• Move a rectangular area within a viewport 

• Move, rotate, and scale a rectangular area within a viewport 

• Scroll a rectangular area 

• Draw fixed-width text to the screen 

• Draw variable-width text to the screen 
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In addition to drawing operations, you can also perform the following window 
management operations using DOPs: 

• Stop removing entries from a window's request queue 

• Start removing entries from a stopped request queue 

• Suspend drawing operations to a window 

• Resume drawing operations in a window 

5.1.1 How to Use DOPs 

To perform a drawing operation, your application must: 

1. Allocate storage for the DOP 

2. Define the structure of the DOP 

3. Initialize any relevant fields of the DOP structure 

4. Execute the DOP 

How you structure DOPs differs depending on which operation you wish to perform; 
initialization varies accordingly. 

How you allocate and execute DOPs also differs depending on whether your 
application uses the UIS windowing environment or provides its own windowing 
services. If an application uses the UIS environment it can use the UISDC routines 
described in Section 5.3 to allocate and execute DOPs. If an application does not use 
the UIS environment, it must allocate and execute DOPs itself. How to do this is 
described in Section 5.4. 

Sections 5.2 through 5.5 provide general information about DOPs that must be 
understood before you attempt to implement any individual operation. Section 5.6 
describes how to structure and initialize DOPs for each type of operation. A 
FORTRAN example accompanies the explanation of each operation in the section. 


5.2 Overview of DOP Structure 

This section is a general description of DOP structure that will be useful in 
understanding how to allocate and execute DOPs. The complete description of 
how to structure DOPs for specific operations is in Section 5.6. 

Each DOP structure is made up of three substructures (blocks): 

Common block — A fixed-size block which must begin all DOP structures. This 
block contains information that all DOPs require, for example, the item—type field 
that identifies which operation the DOP performs and the opcount field that tells how 
many times the operation should be repeated. 
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Unique block — A fixed size block that all DOPs require following the Common 
block. This block contains information that is more specific to a single operation, 
or group of operations, and its fields and their contents vary accordingly. Some 
operations do not utilize the fields in this block, others only utilize some of the fields 
(see the operation-by-operation structure description in Section 5.6 for details) but, 
regardless of utilization, the DOP structure must be padded with the entire Unique 
block. 

Variable block — A variable-length block that contains operation-specific variables 
(that is, coordinates, line lengths). The size of this block varies depending on 
the number of times an operation is repeated. That is, if you specify a draw-line 
operation with an opcount of 1, the Variable block contains the coordinates needed to 
draw one line. If you specify an opcount of 3, then the Variable block must hold the 
coordinates needed to draw 3 lines (and is three times as long). 

Section 5.6 contains an illustration of the Common block along with a full 
explanation of each field in the block. In addition, the section contains illustrations 
and explanations of the specific Unique and Variable blocks needed to define DOPs 
for each type of operation. 


5.3 Implementing DOPs Within the UlS Environment 

If your application runs in the UIS environment, you may use UISDC routines to 
allocate and execute DOPs. 

5.3.1 Allocating Storage for DOPs in the UIS Environment 

To allocate storage for a DOP, use the UISDC$ ALLOC ATE _DOP routine. This 
routine allocates memory for the DOP and also initializes some fields of the Common 
block to default values. UISDC$ ALLOC ATE _DOP has the following format: 
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dop.address = UISDC$ALLOCATEJOP (wd_id, size, atb) 

dop_address Returned address of the DOP. This address is used in subsequent 

routines to execute the DOP. 

Window identifier that you specify. This argument associates the 
DOP with a window by loading the window-related fields of the 
Common block (the window dimensions and the clipping rectangle). 
The window identifier is returned to an application at viewport 
creation time. 

Size, in bytes. This argument is read/write - on input, you specify 
the space for the Variable block; on output, the system returns the 
actual size allocated for the Variable block. The size allocated may 
be smaller than the size you request. Always use the returned size in 
subsequent operations. 

Address of an attribute block which is used to initialize the color, 
writing-mode, and writing-mask fields of the Common block. 

A full routine description of the UISDC$ ALLOC ATE—DOP routine appears in 
Section 5.7. 

Example 5-1 is a FORTRAN program segment that creates a window and allocates 
a DOP to draw 50 points. Note that the input size argument is calculated by 
multiplying the number of times the DOP repeats the operation (the opcount) by 
the predefined constant for the length of a single-operation Variable block 
(DOP_POINTS$C_LENGTH). The SYS$LIBRARY:VWSSYSDEF file defines a 
constant for the length of a single-operation Variable block for each operation, 
see Section 5.5.4.1 for information about predefined data structures. 

Example 5-1 Allocating a DOP 


wd_id 


size 


atb 


! Create a display and window 
VD.ID = UIS$CREATE.DISPLAY (0.0,0.0, 

2 50.0,50.0. 

2 15.0,15.0) 


lower left corner 
upper right corner 
width & height 


WD.ID = UIS$CREATE3IND0W 
2 
2 


(VD.ID, 

’SYS$W0RKSTATI0N^, 
*D0P Drawing Window') 


! display ID 
! device name 
! window banner 


! Allocate the DOP 

SIZE = (50 * D0P_P0INTS$C_LENGTH) 

DOP = UISDC$ALL0CATE^D0P (WD^ID, 

2 SIZE, 

2 0 ) 


variable block 
window ID 
size, in bytes 
default ATB number 
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5.3.1.1 The Allocation Mechanism 

The mechanism the system uses for allocating DOPs provides for efficient use of 
storage in the following ways: 

• It allocates a small amount of storage, if possible. 

• It reuses the storage occupied by DOPs once they have been executed. 

• It waits for storage to be freed when too much is allocated. 

DOPs are allocated in two sizes, by default — 128 bytes (small) and 786 bytes 
(large). You may set the DOP sizes and the number of available DOPs. (See the 
following section.) When you specify the size of the variable portion of the DOP you 
wish to allocate, the system calculates whether it can allocate a small DOP, and does 
so if it can. Otherwise, it allocates a large DOP. 

The system also reuses any storage occupied by an already-executed DOP. Once 
a DOP is executed, it is taken off the request queue (see the next section) and put 
on a return queue. A return queue is a data structure that points to a linked list of 
previously executed DOPs (the DOP Common block provides forward and backward 
links). Each viewport is associated with two return queues; one for small DOPs and 
one for large DOPs. The viewport ID is an address that points to a data structure 
that holds both associated return queues. 

When you allocate a DOP using UISDC$ ALLOC ATE _DOP, the system first checks 
whether a small or large DOP is required. It then attempts to reuse any previously 
executed DOPs of the needed size. If none exists, it allocates a DOP from system 
memory or waits until a DOP is free for reuse. 

5.3.1.2 Modifying DOP Size and Number 

By default, the available sizes and numbers of DOPs are the following: 

• 300 small DOPs; each 128 bytes long 

• 150 large DOPs; each 768 bytes long 

You may use these values or you may wish to alter them to suit your needs. If 
change these values, you must do so before any other processing is done. That is, 
you cannot start using DOPs of one size then change the size and continue. 

You may modify the default sizes of the small and large DOPs with the following 
restrictions: 

• Small DOPs must be within the range 128-512, inclusive. 

• Large DOPs must be within the range 768-16384, inclusive. 

You may also modify the number of available DOPs with the following restriction: 

• There must be a minimum of 110 small DOPS and 110 large DOPs. 
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Note that the default DOP setup allocates 300 pages of PI address space for DOPs. 
If your modifications to size and number of DOPs results in the need for more than 
300 pages, do the following: 

1. Increase the logical value UIS$Pl^POOL-_SIZE by the increased size in bytes. 

2. Increase the SYSGEN parameter, CTLPAGES by the increased size in pages. 

To modify the size and number of DOPs, redefine the following logical values, as 
appropriate. 


UIS$SM ALL _DOP_SIZE 
UIS$L ARGE _DOP_SIZE 
UIS$NUMBER_OF_SMALL _DOPS 
UIS$NUMBER_OF_LARGE_DOPS 


Size of a small DOP. Default is 128. 

Size of a large DOP. Default is 768. 

Number of available small DOPs. Default is 300. 
Number of available large DOPs. Default is 150. 


5.3.2 Executing DOPs in the UlS Environment 

Once you have defined, allocated and initialized a DOP, you are ready to execute it. 
You have three options when executing DOPs: 

1. Execute the DOP synchronously, using the UISDC$EXECUTE_DOP—SYNCFi 
routine. 

2. Execute the DOP asynchronously with completion notification, using the 
UISDC$EXECUTE_DOP_ASYNCH routine. 

3. Execute the DOP asynchronously without completion notification, using the 
UISDC$QUEUE_.DOP routine. 

The difference between the two types of asynchronous execution is that the 
UISDC$EXECUTE_D0P-JVSYNCH routine takes an I/O status block (lOSB) that 
your application can use to check for completion notification. UISDC$QUEUE^DOP 
queues the DOP for execution, but provides no way of telling when the operation 
is completed (it is more efficient). Complete descriptions of these routines and their 
arguments appears in Section 5.7. 


PERFORMANCE NOTE: The UISDC$QUEUE_«DOP routine is much more 
efficient than the other routines; use it whenever an option exists. 

The following FORTRAN program segment defines and initializes a DOP using 
a subroutine (the recommended method for FORTRAN) and queues a DOP for 
asynchronous execution without completion notification. 
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Example 5-2 Queuing a DOP for Execution 

! Allocate the DOP 


! Call subroutine to initialize DOP 

CALL SUB.STRUCTURE (7,VAL(D0P) , ! address of DOP 

7„VAL(D0P+D0P$C_LENGTH)) ! address of a variable 

! block 

! Queue the DOP asynchronously 

CALL UISDC$QUEUE_DOP (WD.ID, ! window ID 

2 7oVAL(DOP)) ! DOP address, by value 

5.3.2.1 The Execution Mechanism 

DOPS are executed using a mechanism called a request queue. Each viewport has 
a request queue associated with it. A request queue is simply a linked list of any 
DOPs that have been submitted to a viewport for execution. Viewport IDs (including 
the systemwide viewport ID) are actually addresses that point to the request queue 
structure associated with the viewport. The request queue structure contains the 
starting address of the linked list of DOPs. Each DOP contains forward and 
backward links (in its Common block) to other DOPs in the list. These links are 
updated by the system when a DOP is submitted or executed. 

When you execute a DOP, you must provide the above-mentioned routines with 
the window ID of the viewport in which you wish to execute the DOP (returned in 
the UISSCREATE—WINDOW call) and the address of the DOP (which is returned 
by UISDC$ALLOCATE—DOP). These arguments provide the system with the 
information needed to associate the DOP with the correct request queue. 


5.4 Implementing DOPs in a Non-UIS Environment 

If your application does not make use of the UIS windowing system; for example, if 
it provides its own windowing system, it must allocate and execute DOPs itself. The 
following sections describe how an application allocates storage for DOPs and how it 
inserts them on the request queue for execution. 
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5.4.1 Allocating Storage for DOPS in a Non-UIS Environment 

Before allocating new storage for a DOP you should check the associated return 
queue to determine if any reusable storage is available on the queue. Use the 
viewport ID to access the return queue — it is the address of the DOP Queue 
structure (in which the return queue resides). See Appendix B for a full description 
of the data structure. Remember, there are actually two return queues associated 
with each viewport one for the large DOPs and one for the small DOPs. The size of 
a DOP depends on the amount of information needed to fully describe the requested 
drawing operation(s). Use the MACRO REMQUE instruction to remove a DOP from 
the return queue. 

If no reusable storage exists, allocate storage using the LIB$GET—VM routine. 

The following example creates a viewport then allocates a DOP by first checking 
the return queue. Note that the MACRO module must be compiled separately and 
linked with a FORTRAN program. 
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Example 5-3 Allocating a DOP 

PROGRAM DELETE_VIEWPORT 
IMPLICIT INTEGER*4(A-Z) 

INCLUDE ’VWSSYSDEF’ 

INCLUDE ’($I0DEF)’ 

INTEGER*2 CHAN.VPl 

! Declare URD 
INTEGER*2 URD1_VP1(6) 

! Load URDl.VPl buffer 

URD1_VP1(1) = 0 ! lower left corner 

URD1_VP1(2) = 0 

URD1_VP1(3) = 99 ! upper right corner 

URD1_VP1(4) = 99 

URD1_VP1(5) = 10 ! absolute coordinate base 

URD1_VP1(6) = 10 

! Define and start VPl 

CALL VIEWPORT (URDl.VPl, CHAN_VP1. VP1_ID) 

! Get a Draw Lines DOP for VPl 

SIZE = (4 * DOP_LINE$C_LENGTH) ! calculate size 

CALL GET.DOP (VPl.ID, SIZE. DOPl) 


! * Get DOP Subroutine * 

SUBROUTINE GET_D0P (VIEWPORT.ID, SIZE. DOP) 
IMPLICIT INTEGER*4(A-Z) 

! Declare external MACRO routine 
EXTERNAL DOPSREMQUE 


DOP = DOP$REMQUE (VIEWPORT_ID. 
2 SIZE) 


(Continued on next page) 
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Example 5-3 (Cont.) Allocating a DOP 

! If none on return queue, calculate size and allocate one. 

IF (DOP .EQ. 0) THEN 

CALL TEST_SIZE C/oVALCVIEWPORT^ID) . ! viewport ID > return Q 

2 SIZE) 

! Allocate appropriate size DOP 
CALL LIB$GET_VM (SIZE, 

2 DOP) 

END IF 

RETURN 

END 

! * TEST.SIZE SUBROUTINE * 

SUBROUTINE TEST.SIZE (REQ,SIZE) 

IMPLICIT INTEGER*4(A~Z) 

INCLUDE ’VWSSYSDEF’ 

! Associate the predefined structure w/ REQ 
RECORD /REQ^STRUCTURE/ REQ 

IF (SIZE .GT. REQ.REQ$W_SMALL_DOP^SIZE) THEN 
SIZE = REQ.REQSW^LARGE^DOP^SIZE 
ELSE 

SIZE = REQ.REQ$W_SMALL_DOP_SIZE 
END IF 

RETURN 

END 

; Separate MACRO Module 


.title rem^que - does a remque 

$D0PDEF 

$REQDEF 


(Continued on next page) 
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Example 5-3 (Cont.) Allocating a DOP 

; + + 

; dop$remque - remove a DOP from the return queues and return it 
; description: 

; This routine will return a DOP or zero if none is 

; available. The size is used to determine whether to use a large 
; or small DOP. Note: that it is possible that the size is larger 
; than the DOP returned, if this is the case then the application 
; must break the request down into smaller chunks and use several 
; large DOPs. 

; Calling sequence: 

: DOP = DOP$REMQUE(VIEWPORT_ID,SIZE) 

; Outputs: 

; DOP = ZERO if no DOPS available on the queue 

.entry dop$remque,0 

movl @4(ap),rl 

cmpw @8(ap),req$w_small_dop_size(rl) 

bgtr 10$ 

remque @req$l_return_flink(rl),r0 
bvs 90$ 

ret 

; We need a large DOP 

10$: remque @req$L_return_large_flink(Rl),r0 

bvs 90$ 

ret 

; Can't get the DOP we want 

90$: clrl rO ; signal error (return zero) 

ret 
. end 


gen a large uur 

none of these then return 

all set then return 


get req address 

check for small or large DOP 

try to get a DOP 

nope then clear rO and return 


5.4.2 Executing a DOP in a Non-UIS Environment 

To execute a DOP in a non-UIS environment, an application must insert the DOP on 
the request queue. To insert a DOP on the request queue, use the MACRO INSQUE 
instruction. Use the viewport ID to access the request queue — it is the address of 
the DOP Queue structure (in which the return queue resides). See Appendix B for a 
full description of the data structure. 
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The following example creates a viewport, allocates a DOP, loads the DOP with the 
necessary information, and inserts the DOP on the request queue. Note that the 
MACRO module must be compiled separately and linked with a FORTRAN program. 

Example 5-4 Inserting a DOP on the Request Queue 


! Declare external MACRO routine 
EXTERNAL DOP$INSQUE 


! Define and start VPl 

CALL VIEWPORT (URDl.VPl, CHAN^VPl. VP1_ID) 

! Get a Draw Lines DOP for VPl 

SIZE = (4 * DOP_LINE$C_LENGTH) ! calculate size 

CALL GET_D0P (VPl.ID, SIZE, DOPl) 

! Call the draw lines subroutine for a border 
CALL D.LINES C/oVALCDOPI) . ! DOP address, by value 

2 y,VAL(DOPl+DOP$C_LENGTH), ! var. block address 

2 SIZE) ! DOP size 

! Queue the DOP by calling a MACRO subroutine 

CALL DOP$INSQUE C/oVALCDOPl) . ! DOP address, by value 

2 VPl^ID) ! viewport ID 


Separate MACRO Module 

.title ins.que - does an insque tail 

SDOPDEF 

$REQDEF 


(Continued on next page) 
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Example 5-4 (Cont.) Inserting a DOP on the Request Queue 

; + + 

; dop$insque - inserts a DOP at the tail of the return queue 
; calling sequence: 

; CALL DOP$INSQUE(DOP.VIEWPORT.ID) 

; OUTPUTS: 

: NONE 

.entry dop$insque,0 

movl 4(ap),r0 

movl @8(ap),rl 

insque (RO),@req$L_request_blink(Rl) 

movl #l,rO ; indicate success 

ret 

. end 

5.5 Structuring and Initializing DOPs 

As mentioned briefly above, each DOP structure is made up of three blocks — the 
Common block, the Unique block, and the Variable block. The fields of the Common 
block are the same across operations, while those of the Unique and Variable blocks 
vary depending on the operation being performed. 

The later part of this section (Section 5.6) is designed to provide easy reference for 
programming DOPs. It contains the following: 

• An illustration and description of the Common block 

• Separate illustrations and descriptions of the Unique block and Variable block for 
each operation 

• FORTRAN examples accompanying the description of each operation 

For quick reference, the running head of each page reflects the operation being 
described on that page. 

Before proceeding to Section 5.6, read the following sections for general information 
about structuring DOPs and using the reference section. 
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5.5.1 The Common Block 

The Common block is a fixed-size block that must begin all DOP structures. It 
contains a number of fields (described completely in Section 5.6), but two in 
particular affect the subsequent structure of the DOP — the item^type field and 
the operation count opcount field. 

The item^type field determines which operation the DOP performs, and so affects 
which Unique and Variable blocks must be specified. You must explicitly specify the 
item type using a predefined constant (defined in SYS$LIBRARY:VWSSYSDEF). The 
table that follows lists the symbolic constants used to specify all possible drawing 
operations along with a brief description of each. 


Constant 

Operation 

D0P$C_DRAW_L1NES 

Draw line(s) or polygon. 

DOP$C_DRAW_COMPLEX_LINE 

Draw a complex patterned line with a sloped length 
and width. Also draws a filled polygon. 

DOP$C_DRAW_POINTS 

Draw point(s). 

DOP$C_FILL -POLYGON 

Draw a filled polygon with a specified pattern. 

DOP$C_FILL-POINT 

Fill a point with a specified pattern. 

DOP$C-FILL-LINES 

Fill a line with a specified pattern. 

DOP$C-DRAW-FIXED-TEXT 

Draw text with a specified fixed-space font. 

DOP$C-DRAW-VAR-TEXT 

Draw text with a specified variable-spaced font. 

DOP$C-MOVE-ROTATE-AREA 

Move an area with specified rotation and scaling. 

DOP$C-MOVE -AREA 

Move an area within a viewport. 

DOP$C-SCROLL -AREA 

Move area in a viewport. Fill the vacated area with 
background color 

DOP$C-STOP 

Stop removing entries from this request queue. 

This used when manipulating the screen to handle 
occlusion. 

DOP$C-START 

Start removing entries from the specified request 
queue. This request can only be made from the 
system viewport. 

DOP$C-DELETE -BITMAP 

Delete an offscreen bitmap. 

DOP$C-SUSPEND 

Do not remove any more DOPs from this request 
queue until the queue is resumed. 

DOP$C-RESUME 

Resume processing DOPs on the specified queue. This 
request can only be made from the system viewport. 


The opcount field indicates how many times the operation should be repeated. That 
is, if the specified item^type is dop$c_draw_lines and the opcount is 4, the DOP 
will draw four lines. This affects the structure of the DOP because the size of the 
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Variable block varies with the number of operations (more coordinates are necessary 
to perform the additional operations). 

5.5.2 The Unique Block 

The Unique block is a fixed-size block. This block contains information that is, 
specific to a single operation or group of operations, and its fields and their contents 
vary accordingly. Every DOP structure must include the Unique block whether or 
not it utilizes the fields in the block. That is, if a particular operation only uses three 
words of the Unique block, the Unique block of the DOP structure must be padded 
to its full length. 

Section 5.6 illustrates and explains the fields in the Unique block that are relevant for 
each operation. 

5.5.3 The Variable Block 

The Variable block is a variable-size block. It contains operation-specific variables 
(that is coordinates, line lengths). The size of the block varies depending on the 
number of operations the DOP is to perform. To clarify, if you specify a draw-line 
operation with an opcount of 1, the Variable block contains the coordinates needed to 
draw one line. If you specify an opcount of 3, then the Variable block must hold the 
coordinates needed to draw 3 lines (and be three times as long). 

Section 5.6 illustrates and explains the fields in the Variable block that are needed 
for a single occurrence of each operation. It also lists the predefined constant for the 
length of a one-operation Variable block. This constant is useful for calculating the 
input size argument of the UISDC$ ALLOC ATE—DOP routine. Simply multiply the 
constant by the number of times the DOP is to repeat the operation (the opcount). 

5.5.4 Programming Considerations 

When programming an application that performs drawing operations, you have 
several options for how to implement the DOP structure. Depending on the language 
in which you are writing and the exact nature of the operation, you can: 

• Use the predefined structure provided in the SYSLIBRARYiVWSSYSDEF file 

• Define the full DOP structure using your language's structured-type statements 

Using the predefined DOP structure prevents having to explicitly construct the DOP 
in your application. However, in some cases, it is not always possible to use the 
predefined structure. 
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5.5.4.1 The Predefined OOP Structure 

The system provides a DOP definition file located in SYSLlBRARY:VWSSYSDEF./an 
- where Ian is the file extension for the language you are using. (You choose which 
language definition files are created when you install the system.) 

VWSSYSDEF defines DOP-related constants, including offset values that define each 
field in the DOP structure. You can use these predefined offsets in your application 
to initialize the DOP fields. Remember, the system allocates the DOP storage; you 
must associate a structure with the storage in order to initialize the proper fields. The 
offsets provide a way of accessing fields within the structure. Section 5.6 labels each 
field in the DOP illustrations with its predefined offset. 

For example, VWSSYSDEF defines an offset DOP$WJTEM__TYPE which identifies 
the location of the item^type field in the DOP. Once you associate the returned 
storage with a structure, you can use the offset to reference into the structure. 

You must "include" or "insert" the VWSSYSDEF file in each module in which you 
reference it in order to use any predefined constants and offsets. You should become 
familiar with the way in which the VWSSYSDEF file defines the DOP structure for 
the programming language you are using. 

Initializing fields using the offsets is straightforward when applied to the fixed 
portion of the DOP (the Common and Unique blocks), but is somewhat more 
complex when applied to the Variable block. The VWSSYSDEF file only defines 
offsets for one occurrence of an operation in the Variable block and they are offset 
from the end of the fixed portion. To clarify, to draw a single line, the Variable 
block for a Draw Lines operation requires four fields, which have predefined 
offsets; however, to draw two lines, it requires eight fields — but only four offsets 
are predefined. To write to the second set of fields, you can use the same offsets, but 
you must change the point from which they are offset. 

In languages that support arrays of structures, such as PASCAL, you can define an 
array of Variable block structures, and increment the original offset by the length 
of a "one-operation" Variable block. The VWSSYSDEF file provides constants for 
both the offset and Variable block length. The original offset (the end of the fixed 
portion) is DOP$C_LENGTH and the constants for the "one-operation" Variable 
block lengths are listed with the respective operation in Section 5.6. 

In a language that does not support arrays of structures, such as FORTRAN, you 
have two options: 

• Completely define the structure of the Variable block using a STRUCTURE 
statement. 

• Define a structure the size of a one-operation Variable block. Then, to initialize 
the DOP for series of operations, use a loop that increments the offset. 

For a one-operation case, FORTRAN can simply use the predefined offsets. 
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The examples that accompany the operation descriptions are written in FORTRAN; 

the following section describes the conventions that they follow. 

5.5.4.2 Using the Examples 

The examples provided in the DOP reference section are in FORTRAN. They are 

subroutines that construct the DOP structure and initialize any necessary fields. 

To eliminate redundancy, the calling program does not appear in each example. 

However, a typical calling program appears below for the sake of illustration. The 

sample calling program does the following: 

• Creates a display and window. 

• Allocates storage for a DOP that draws a box (4 lines — opcount equals 4). 

• Passes the returned DOP address to a subroutine that defines and initializes the 
DOP structure. (This must be done in FORTRAN to avoid reallocating storage 
during the structure declaration — other high-level languages can avoid the 
subroutine call by using a pointer to associate the structure with the allocated 
storage.) It also passes the address of the Variable block (which is calculated by 
adding the length of the fixed portion of the DOP to the DOP address). 

• Queues the DOP for execution. 

• Hibernates the process (so the result can be viewed). 


NOTE: The examples assume that the application is using the UIS/UISDC 
interface. 
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Example 5-5 Calling Program for Example Subroutines 


PROGRAM DRAW.LINES 
IMPLICIT INTEGER*4(A-Z) 
INCLUDE ’UISENTRY’ 
INCLUDE ’VWSSYSDEF’ 


! Create a display and window 
VD_ID = UIS$CREATE_DISPLAY (0.0,0.0, 

2 50.0,50.0, 

2 15.0,15.0) 


lower left corner 
upper right corner 
width & height 


WD^ID = UIS$CREATE^WINDOW (VD^ID, 

2 *SYS$WORKSTATION», 

2 *D0P Drawing Window*) 


display ID 
device name 
window banner 


! Allocate the DOP 

SIZE = (4 * DOP_LINES$C_LENGTH) 

DOP = UISDC$ALLOCATE_DOP (WD_ID, ! window ID 

2 SIZE, ! variable portion size, in bytes 

2 0) ! default ATB number 

! Call the subroutine 

CALL SUB.STRUCTURE (y,VAL(D0P), ! DOP address 

yoVAL(DOP+DOP$C^LENGTH)) ! Var. block address 

! Queue the DOP asynchronously 

CALL UISDC$QUEUE^DOP (WD^ID, ! window ID 

2 yoVAL(DOP)) ! DOP address, by value 

CALL SYS$HIBER() 

END 

NOTE: In FORTRAN, you must pass the DOP address that UISDC—$ALLOCATE 
returns by value to a subroutine. The subroutine associates the address with a record 
structure using the RECORD statement. If this were not done in a subroutine, the 
RECORD statement would redundantly allocate storage for the DOP. 


5.6 The DOP Reference 

This section is designed to provide an easy reference for structuring DOPs. 

It contains the following: 

• An illustration and detailed description of the the Common block structure 

• An illustration and detailed description of the Unique and Variable block 
structure for each operation 

• A description of how to perform each operation 
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• A program example of how to perform each operation 

The Common block is described first, then each operation is described separately. 
The operations are listed in alphabetical order. The running head reflects which DOP 
is described on a page. 

Each block is accompanied by the record name associated with the block in the 
SYS$LIBRARY:VWSSYSDEF definition file, and each field lists the predefined field 
name. These names can be used to reference into the DOPs. 

NOTE: The descriptions assume that an application is using the UIS/UISDC 
interface to allocate and execute DOPs and to load bitmaps. You may perform these 
functions without using the UIS/UISDC interface. 
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Common Block 

Common Block 

This is a description of the Common block of the DOP structure. The 
structures of all DOPs must begin with the Common block. 

Common block (dop—Structure) 

DOP$L_FLINK 

DOP$L_BLINK 

DOP$B_SUB_TYPE DOP$B_TYPE DOP$W_SIZE 


DOP$L_DEC_RESERVED 
DOP$L _DEC_RESERVED2 
DOP$L _USER_RESERVED 


DOP$W_OPCOUNT 

DOP$W_FLAGS 

DOP$W_MODE 

DOP$W_ITEM_TYPE 

DOP$L. 

_MASK 


DOP$L_SOURCE_INDEX 

DOP$L_FCOLOR 

DOP$L_BCOLOR 

DOP$L_BITMAP_ID 

DOP$L_BITMAP_GLYPHS 

DOP$W_VP_MAX_Y I DOP$W_VP_MAX_X 

DOP$W_DELTA_X 


DOP$W_DELTA_Y 

DOP$W_VP_MIN_Y 


DOP$W_VP_MIN_X 
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Common Block 


Field 

DOP$L_FLINK 

DOP$L-BLINK 

DOP$W_SIZE 
DOP$B_TYPE 
DOP$B_SUB_TYPE 
DOP$L -DEC-RESERVED 
DOP$L -DEC-RESERVED2 
DOP$L -USER-RESERVED 
DOP$W_FLAGS 


Description 

This field contains the DOP queue forward link, which is the 
address of the preceding DOP in the request queue. 

This field contains the DOP queue backward link, which is 
the address of the subsequent DOP in the request queue. 

Size of the DOP in bytes. 

Structure type of the DOP. 

This field is reserved for use by DIGITAL. 

This field is reserved for use by DIGITAL. 

This field is reserved for use by DIGITAL. 

This field is reserved for use by the user. 

The following fields are defined within DOP$W—FLAGS: 
DOP$V__DELETE— This field is 1 bit long, and starts at 
BITMAP bit 0. When this field contains a value 

of 1, the offscreen source bitmap 
(identified in the bitmap—ID field) is 
deleted when the operation completes. 

DOP$V_SYSTEM_ This field is 1 bit long and starts 
DOP at bit 1. When this field contains a 

value of 1, the DOP is returned to 
the system return queue when the 
drawing operation is completed. A 
window manager specifies this when 
it needs to draw in the systemwide 
viewport or when it allocates a system 
DOP to draw on a user's viewport. 


This field is 1 bit long, and starts 
at bit 2. When this field contains a 
value of 1, the DOP is not returned to 
the return queue when the drawing 
operation is completed and is not 
deleted. This is useful in cases where 
an application wishes to preserve 
information in the DOP, possibly in 
the user-reserved field. 

DOP$W_OPCOUNT Number of drawing operations requested by this packet. 

For example, if the drawing operation you request is "draw 
points", this field indicates how many points should be drawn 
(using coordinates in the variable portion of the DOP). 


DOP$V_NO_ 

RETURN 
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Field 

Description 

DOP$W_ITEM_TYPE 

Type of drawing operation requested by DOP. The following 
is a list of the s)ntnbolic constants used to specify all possible 
drawing operations: 

DOP$C^DRAW_LINES 

DOP$C--DRAW-.COMPLEX^LINE 

DOPSC-DRAWJOINTS 

DOP$C JILL -POLYGON 

DOP$C-FILL-POINT 

DOP$C-FILL-LINES 

DOP$C-DRAW-FIXED-TEXT 

DOP$C-DRAW-VAR-TEXT 

DOP$C-MOVE-ROTATE-AREA 

DOP$C-MOVE-AREA 

DOP$C-SCROLL -AREA 

DOP$C-STOP 

DOP$C-START 

DOP$C-DELETE-BITMAP 

DOP$C-SUSPEND 

DOP$C-RESUME 

DOP$W_MODE 

Writing mode code as expected by QDSS. There are 16 
different writing modes that you can specify using constants 
listed in Appendix C. 

DOP$L_MASK 

This field must be -1. 

DOP$L -SOURCE-INDEX 

Source index. Used with the writing mode to determine the 
result of overlaid colors. (See the Description section.) 

DOP$L-FCOLOR 

Foreground color index. This is an index into the color map 
that is used for the foreground (or writing) color. 

DOP$L-BCOLOR 

Background color index. This is an index into the color map 
that is used for the background color. 

DOP$L-BITMAP-ID 

ID bitmap. Used to identify bitmaps in text images, pattern 
fill, and delete bitmap operations. This value is 0 if the 
operation is not related to bitmaps. 

DOP$L -BITMAP-GLYPHS 

Bitmap backing store address. If a stored bitmap is paged out 
of the bitmap storage area, the address at which it is stored in 
VAX memory is loaded into this field. 

DOP$W-VP-MAX_X 

Viewport relative device coordinate maximum X. Used to 
determine the upper right comer of the viewport. 

DOP$W-VP-MAX-Y 

Viewport relative device coordinate maximum Y. Used to 
determine the upper right comer of the viewport. 





July 1987 


Using Drawing Operation Primitives 5-23 
Common Block 


Field Description 

Delta from the lower left corner of the viewport to the lower 
left comer of the clipping rectangle (the actual writing area). 

Delta from the lower left corner of the viewport to the lower 
left comer of the clipping rectangle (the actual writing area). 

Viewport relative device coordinate minimum X. Used to 
determine the lower left comer of the viewport. 

Viewport relative device coordinate minimum Y. Used to 
determine the lower left corner of the viewport. 


Description 


DOP$W_DELTA_X 

DOP$W_DELTA_Y 

DOP$W-.VP-_MIN_X 

DOP$W_VP_MIN_Y 


The Common block is a fixed-size block that must begin all DOP structures. 
A number of the fields in this block must be loaded in every DOP, while 
other fields in the block are important only to specific types of operations (for 
example, color operations and bitmap operations). 


Required fields 

The number of fields you must explicitly load will differ, depending on 
whether your application is running in the UIS environment. 

If your application is not running in the UIS environment, it is responsible for 
loading all relevant fields of the Common block. That is, any field needed for 
the particular DOP except for the first six fields — is loaded by the system 
during allocation. Section 2.16.2 contains an example that initializes the 
entire Common block. 

If your application runs in the UIS environment, some of the Common block 
fields that must be initialized are actually loaded by UISDC$ ALLOC ATE _DOP 
after it allocates storage for the DOP, while others must be explicitly 
initialized by your application. The following sections list the fields in these 
two categories. 

Default Initialization — UISDC$ALLOCATE—DOP initializes some fields, 
using the attribute block the application specifies in the routine call. They 
are the following: 

• Writing mode 

• Foreground and background colors 

• Viewport minimum and maximum coordinates 

• Clipping rectangle delta coordinates 





July 1987 


5-24 Using Drawing Operation Primitives 

Common Block 


You may affect any of these fields by modifying the ATB before the allocation 
or by directly overriding the initialization after allocation. 

The following fields, initialized by the ALLOCATE routine, are used for the 
DOP execution mechanism: 

• Forward link 

• Backward link 

• Size 

• Type 

• Sub—type 

While you may access these fields, you should not attempt to modify them. 

Explicit Initialization — The fields that your application must explicitly 
initialize are the iteni-Jype field and the opcount field. 

The item^type field identifies which operation the DOP performs. You 
specify one of the symbolic constants listed above to initialize this field. 

The opcount field tells how many times the operation should be repeated. 
That is, if you specify a Draw Lines operation with an opcount of 1, one line 
is drawn. If you specify an opcount of 3, three lines are drawn. This field is 
directly related to the Variable block of a DOP. The Variable block contains 
the coordinates needed to draw a line (in this example). To draw three lines, 
the Variable block must hold the coordinates needed to draw three lines (and 
be three times as long). 

Color Fields 

The following fields in the Common block may be used to manipulate color: 

• Foreground color index 

• Background color index 

• Writing mode 

• Source index 

The foreground color index and background color index determine the color to 
use for writing and background, respectively. Modifying the index changes 
the color on a per-operation basis. That is, DOPs can write in different colors 
to the same viewport. 

The writing mode is used to determine how writing operations use foreground 
and background colors to display graphic objects; for example, whether 
objects overlay one another on the screen or negate each other. There are 16 
writing modes (see Appendix C). 
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The source index is an index number that is used to determine the color 
interaction of objects being written to the screen with objects already existing 
on the screen. The source index involves the interaction of: 

• The state of the pixels in existing bitmap 

• The specified source index value 

• The specified writing mode 

• The specified foreground and background colors. 

• The use—mask modifier of the writing mode (if specified) 

• The specified source bitmap (if bitmap—id field is specified) 

The following figure demonstrates how the source index works. (This figure 
does not specify the source bitmap or the use—mask writing mode modifier.) 

Figure 5-1 illustrates two intersecting circles. Circle A is written with a 
foreground index of 010 (binary — as are all numbers in this example) and 
a background index of 100 (remember, the indexes represent colors in the 
color map — to simplify this example, only three bits are used to represent 
pixel settings). Circle B is written with a foreground index of 001 and a 
background index of 100. The specified source index value is 001 and the 
specified writing mode is WRIT$DSO (destination ORed with source). 

Figure 5-1 How the Source Index Works 


Circle A 

FG = 010 
BG = 100 



Circle B 

FG = 001 
BG = 100 


Drawn using 101 as color map index 


Source Index = 001 


MLO-1069-87 


When objects are written to the screen, the system performs a logical 
operation on the present contents of the screen bitmap and the source index. 
The logical operation is determined by the specified writing mode. Because 
the DSO mode was specified in Figure 5-1, Circle A's foreground index 010 
is ORed with the source index, 001, resulting in the number 011. 
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The system uses the following procedure to determine the color map index 
to use for writing: 

• If the bit position in the resulting number includes a 1, the system checks 
the corresponding bit position in the foreground index and sets or clears 
the bit to agree with the foreground index. 

• If the bit position in the resulting number includes a 0, the system checks 
the corresponding bit position in the background index and sets or clears 
the bit to agree with the background index. 

In Figure 5-1, the number resulting from the logical operation is 101, so the 
intersecting portion of the circles is written in the color represented by 101 in 
the color map. 

When you specify a bitmap and/or the use_mask writing mode modifier, 
this process gets more complicated. The following equations describe how to 
determine the result of any intersection on the screen. (In Figure 5-1, steps 
2 and 5 are not meaningful because these options are not specified.) 


STEP 1 

IF (source_bitmap exists AND 
bitmap^index = source^bitmap = 0) THEN 

0 

ELSE 

source.index 

If you specify a bitmap to be used by the DOP (with the bitmap ID), 
the driver creates a bitmap index by inserting the source index in any bit 
position where a 1 occurs in the bitmap. The source—bitmap is 1 bit while the 
resulting bitmap—index reflects the number of planes of color used. 


STEP 2 

mask = IF use_mask THEN 
bitmap.index 
ELSE 
-1 

If you specify the use_mask modifier as part of the writing mode, the 
bitmap—index is used as the mask. 


STEP 3 

(data) 


IF use_mask THEN 
logical operation source_index 
ELSE 

bitmap_index 


= fg_bg_selector 
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To attain the foreground and background selector perform a logical operation 
on the data on the screen and either the source—index value (if use—mask was 
specified) or the bitmap—index. The logical operation is determined by the 
specified writing mode. 


STEP 4 

( fg AND fg_bg_selector) OR (bg AND (NOT fg_bg_selector)) = tl 

The value of the foreground and background selector determines which 
bits are set to foreground and background colors — fg and bg refer to the 
foreground and background colors specified in the DOP. (tl is the data 
output to screen in cases where no mask is specified.) 


STEP 6 

(tl AND mask) OR (data AND (NOT(mask)) = final_data 

The mask and tl are used to determine the data output to the screen. 

Bitmap Fields 

Two fields in the Common block are used with bit map operations. (Bitmap 
operations may be text or fill-pattern operations.) They are the bitmap^D 
field and the bitmap—glyphs field. 

An operation that uses a bitmap must first load the bitmap from processor 
memory into offscreen bitmap memory, using the UISDC$LOAD_-BITMAP 
routine. That routine returns a bitmap—ID that identifies the loaded bitmap 
in offscreen memory. 

To use that bitmap in a bitmap-related DOP, your application must initialize 
the bitmap—ID field with the returned ID. For example, once you have loaded 
a bitmap and initialized the bitmap—ID field of a Fill Polygon DOP, the DOP 
will use the bitmap pattern to fill the polygon it creates. 

The bitmap—glyphs field allows the system to retrieve the bitmap that is not 
available in offscreen memory. The bitmap—glyph is the address (in processor 
memory) at which the bitmap is stored. If a DOP requires the bitmap, it is 
swapped back in. 

NOTE: The bitmap—glyph address must remain valid and not be reused 
until a Delete Bitmap DOP has been executed and that DOP has completed. 
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Miscellaneous Fields 

The writing mode field specified in a DOP affects the way the drawing 
operations appear on the screen. On a QDSS system, the screen is more 
than 1 bit deep. Some operations (such as Move Area) may require a writing 
mode other than the default to operate properly. 

By setting bits in the flags field, you may do the following: 

• Delete the bitmap specified in the bitmap^D field. This is typically done 
for a "one-shot" bitmap DOP. The DOP is performed, then the bitmap is 
deleted from offscreen memory. 

• Not return a DOP for reuse. Again this is typically done for a "one- 
shot" DOP. This prevents information contained in the DOP from being 
overwritten. 

• Return the DOP storage to the systemwide return queue. This is done 
when a DOP is allocated from the systemwide viewport and inserted on 
another viewport's request queue. 

Examples 

The examples in the operation-specific sections show how to initialize the 
Common block for each drawing operation. 

Initializing the Variable Block 

The QDSS bitmap-memory coordinate system uses an X coordinate that 
increases from left to right and a Y coordinate that increases down. For 
example, to access the top left-hand comer of a bitmap in QDSS memory, 
specify a 0 for both the X and Y source coordinates. 
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Delete Bitmap 

The Delete Bitmap operation permits you to delete a bitmap specified in the 
bitmap—ID field of the common block. 


Unique block 

The Unique block is not relevant to this operation. 


Variable block 

The Variable block is not relevant to this operation. 


Description 

The Delete Bitmap operation permits you to delete a bitmap that you specify 
in the bitmap—ID field of the Common block. 

Since this is a queued operation, make sure that bitmap glyphs being 
maintained by the application remain valid until Delete Bitmap has been 
executed. 

Relevant Common Block Fields 

You specify the bitmap ID of the bitmap you wish to delete in the Common 
block. 

Initializing the Variable Block 

The QDSS bitmap-memory coordinate system uses an X coordinate that 
increases from left to right and a Y coordinate that increases down. For 
example, to access the top left-hand corner of a bitmap in QDSS memory, 
specify a 0 for both the X and Y source coordinates. 
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Draw Complex Line 

The Draw Complex Line operation permits you to draw a line or patterned 
line of variable width with a slope in both the length and width direction. 


Unique block 

The Unique block is not relevant to this operation. 


Variable block (dop_move_r_array) 


DOP_MOVE_R$W_X_SOU RCE 

DOR_MOVE_R$W_FILLER 

DOP_MOVE_R$W_WIDTH 

DOP_MOVE_R$W_Y_SOURCE 

DOP_MOVE_R$W_J(_TARGET 

DOP_MOVE_R$W_HEIGHT 

DOP_MOVE_R$W_X_TARGET_VEC1 

DOP_MOVE_R$W_Y_TARGET 

DOP_MOVE_R$W_L _TARGET_VEC1 

DOP_MOVE_R$W_Y_TARGET_VEC1 

DOP_MOVE_R$W_Y_TARGET_VEC2 

DOP_MOVE_R$W_X_TARGET_VEC2 


DOP_MOVE_R$W_L_TARGET_VEC2 
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Field 


Use 


DOP_MOVE_R$W_FILLER 
DOP_MOVE_R$W_X-SOURCE 

DOP_MOVE_R$W_Y_SOURCE 

DOP_MOVE_R$W_WIDTH 

DOP_MOVE_R$W_HEIGHT 

DOP_MOVE_R$W_X_TARGET 

DOP_MOVE_R$W_Y_TARGET 

DOP_MOVE_R$W_X_TARGET_VECl 

DOP_MOVE_R$W_Y_TARGET_VECl 

DOP_MOVE_R$W_L _TARGET_VEC1 
DOP_MOVE_R$W_X_TARGET_VEC2 

DOP_MOVE_R$W_Y_TARGET_VEC2 

DOP_MOVE_R$W_L_TARGET_VEC2 


This field is reserved for use by DIGITAL. 

If a bitmap_ID is specified in the Common 
block, this field is the X offset into the line style 
bitmap; otherwise, it is ignored. 

If a bitmap_ID is specified in the Common 
block, this field is the Y offset into the line style 
bitmap; otherwise, it is ignored. 

If a bitmap JD is specified in the Common 
block, this field is the width of the line style 
bitmap to be used; otherwise, it is ignored. 

If a bitmap_JD is specified in the Common 
block, this field is the height of the line style 
bitmap to be used; otherwise, it is ignored. 

The X coordinate of the starting point of the line. 

The Y coordinate of the starting point of the 
line. 

The delta of the X coordinate starting point and 
end point of vector 1. 

The delta of the Y coordinate starting point and 
end point of vector 1. 

This field is irrelevant to this operation. 

The delta of the X coordinate starting point and 
end point of vector 2. 

The delta of the Y coordinate starting point and 
end point of vector 2. 

This field is irrelevant to this operation. 


Description 

The Draw Complex Line operation permits you to draw a line or patterned 
line of variable width with a slope in both the length and width direction. 
See the description of the Draw Line DOP (which also draws lines) to see 
which routine is appropriate for the operation you want to perform. 

Relevant Common Block Fields 

You may specify a bitmap ID in the Common block to indicate a line style for 
a complex line. Use the x^ource and y^ource fields of the Variable block to 
specify an offset into the bitmap as a starting point for the line style and use 
the width and height fields to specify the extents of the bitmap to use. 

By default, the system uses a fill pattern of all Is. 
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Initializing the Variable Block 

To draw a complex line, you must specify a starting point and two vectors. 
Vector^l specifies the length of the line and the slope of the length. 
Vector—2 specifies the width of the line and the slope of the width. You 
must specify a delta X and Y value for each vector relative to the target X 
and Y. To determine the proper X and Y values for the vectors, subtract the 
X and Y values of the endpoint from those of the starting point to arrive at a 
delta value. 

The length fields are ignored in this operation. 

The QDSS bitmap-memory coordinate system uses an X coordinate that 
increases from left to right and a Y coordinate that increases down. For 
example, to access the top left-hand corner of a bitmap in QDSS memory, 
specify a 0 for both the X and Y source coordinates. 

PERFORMANCE NOTE: Lines are drawn faster if Vector—1 specifies the 
more gentle slope (less than 45 degrees). 


Example 

The following FORTRAN program draws a complex line to the screen by 
taking the following steps: 

1. Creating a bitmap pattern. 

2. Loading the bitmap, using UISDC$LOAD—BITMAP. 

3. Specifying an opcount of 1. 

4. Initializing the Variable block with the offset and extent of the specified 
bitmap pattern. 

5. Initializing the Variable block with a starting position of (50,50). 

6. Initializing the Variable block with the deltas of the length and width 
endpoint coordinates. 

! Calling program 


* BITMAP FUNCTION * 
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INTEGER*4 FUNCTION GET_BITMAP_ID ! window ID 

! Declare the storage 
IMPLICIT INTEGER*4(A-Z) 

COMMON /WINDOW/ WD_ID. VD_ID 
INTEGER*4 BITMAP.ID 
INTEGER*2 BITMAP(16) 

! Load the bitmap values 
BITMAP(l) = ’AAAA’X 
BITMAP(2) = ’5555’X 
BITMAP(3) = ’AAAA’X 
BITMAP(4) = ’5555’X 
BITMAP(5) = ’AAAA’X 
BITMAP(6) = ’5555’X 
BITMAP(7) = ’AAAA’X 
BITMAP(8) = ’5555’X 
BITMAP(9) = ’AAAA’X 
BITMAP(10) = ’5555’X 
BITMAP(ll) = ’AAAA’X 
BITMAP(12) = ’5555’X 
BITMAPdS) = ’AAAA’X 
BITMAP(14) = ’5555’X 
BITMAP(15) = ’AAAA’X 
BITMAP(16) = ’5555’X 

! Load the bitmap from buffer 
BITMAP_ID = UISDC$LOAD_BITMAP 
2 
2 
2 
2 

GET_BITMAP_ID = BITMAP.ID 
END ! function 

! * COMPLEX LINES SUBROUTINE * 

SUBROUTINE SUB_COMPLEX_LINE (DOP, D0P_VAR) 

INCLUDE ’VWSSYSDEF’ 

! Declare the GET_BITMAP_ID function 
INTEGER*4 GET_BITMAP_ID 

! Associate the predefined fixed structure w/ DOP 
RECORD /DOP_STRUCTURE/ DOP 

! Associate the predefined variable structure w/ D0P_VAR 
RECORD /D0P_M0VE_R_ARRAY/ D0P_VAR 


to QDSS memory 
(WD_ID, ! window ID 

BITMAP, ! bitmap address 

32, ! bitmap length (bytes) 

16, ! bitmap width, in pixels 

1) ! bits/pixel 
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! Load the values 

DOP.DOP$W_ITEM_TYPE = DOP$C_DRAW_COMPLEX_LINE 
D0P.D0P$W_0P_C0UNT = 1 

DOP.DOP$L_BITMAP_ID = GET_BITMAP_ID() ! function call 

D0P_VAR.D0P_M0VE_R$W_X_S0URCE = 0 
D0P_VAR.D0P_M0VE_R$W_Y_S0URCE = 0 
DOP_VAR.DOP_MOVE_R$W_WIDTH = 10 
DOP_VAR.DOP_MOVE_R$W_HEIGHT = 10 
DOP_VAR.DOP_MOVE_R$W_X_TARGET = 50 
DOP_VAR.DOP_MDVE_R$W_Y_TARGET = 50 
D0P_VAR.D0P_M0VE_R$W_X_TARGET_VEC1 = 300 
D0P_VAR.D0P_M0VE_R$W_Y_TARGET_VEC1 = 300 
D0P_VAR.D0P_M0VE_R$W_X_TARGET_VEC2 = -20 
D0P_VAR.D0P_M0VE_R$W_Y_TARGET_VEC2 = -30 

RETURN 

END 
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Draw Fixed Text 

Describes the additional DOP structure needed to fixed-width text to the 
screen. 


Unique block (text—args) 


DOP$W_TEXT_WIDTH 

DOP$W_TEXT_HEIGHT 

DOP$W_TEXT_STARTING_Y 

DOP$W_TEXT_STARTING_X 


Field 

Use 

DOP$W_TEXT_HEIGHT 

Height of each character, in pixels. This value is 
constant for each font. 

DOP$W_TEXT_WIDTH 

Width of each character. 

DOP$W_TEXT_STARTING_X 

The viewport relative X coordinate for the starting 
position of the text on the screen. 

DOP$W_TEXT_STARTING_Y 

The viewport relative Y coordinate for the starting 
position of the text on the screen. 


Variable block (dop—ftext—array) 


DOP_FTEXT$W_OFFSET_Y 


DOR_FTEXT$W_OFFSET_X 


Field 

Use 

DOP_FTEXT$W_OFFSET_X 

The X coordinate of the offset into the font where a 
specific character is located. 

DOP_FTEXT$W_OFFSET_Y 

The Y coordinate of the offset into the font where a 
specific character is located. 


Variable-Length Constant:dop_ftext$c_length 
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Description 

The Draw Fixed Text operation permits you to write fixed-width text to the 
screen. 

To draw scaled, rotated, or differently spaced text, use the Move/Rotate 
DOP. 

Relevant Common Block Fields 

To draw fixed-width text to the screen, you must first load a bitmap that 
contains a fixed-width font from processor memory to the offscreen bitmap 
memory. You load a bitmap, using the UISDC$LOAD_BITMAP routine. 
This routine returns a bitmap ID that must be loaded in the bitmap-JD field 
of the Common block. (See Section 5.7 for details about loading bitmaps 
with the UISDC interface.) 

Initializing the Unique Block 

The Unique block describes the height and width of the specified font and 
the position to start writing on the screen. You must initialize all these fields. 
When writing text, the position you specify as the starting point will be the 
upper left-hand corner of the first character (provided the character height 
is specified as a positive number). This is unlike specifying areas, where the 
starting point is the lower left-hand comer. 

Initializing the Variable Block 

The Variable block indicates which character to write by specifying an offset 
into the font. 

The QDSS bitmap-memory coordinate system uses an X coordinate that 
increases from left to right and a Y coordinate that increases down. For 
example, to access the top left-hand comer of a bitmap in QDSS memory, 
specify a 0 for both the X and Y source coordinates. 


Example 

The following FORTRAN program writes two characters of text to the screen 
by taking the following steps: 

1. Creating a two-letter bitmap — HI (using a function). 

2. Loading the bitmap, using UISDC$LOAD_BITMAP. 

3. Specifying an opcount of 2. 

4. Initializing the Unique block with a starting position of (100,100). 
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5. Initializing the Variable block with the offsets of the two characters. 

Note that the specified offset values seem to write the letters in reverse order. 
This is because of the way VAX memory loads the bitmap; the I is loaded at 
( 0 , 0 ). 


! Calling program 


! Function that defines 
! and loads the bitmap (font) 

INTEGER*4 FUNCTION GET_BITMAP_ID ! window ID 

! Declare the storage 
IMPLICIT INTEGER*4(A-Z) 

COMMON /WINDOW/ WD_ID, VD_ID 
INTEGER*4 BITMAP^ID 
INTEGER*2 BITMAP(16) 

! Load the bitmap values 
BITMAP(l) = »423E’X 
BITMAP(2) = ’4208’X 
BITMAP(3) = *4208’X 
BITMAP(4) = ’4208*X 
BITMAP(5) = ’7E08*X 
BITMAP(6) = ’4208’X 
BITMAP(7) = *4208’X 
BITMAP(8) = ’423E’X 


! Load the bitmap from buffer to QDSS memory 


BITMAP.ID = UISDC$LOAD.BITMAP (WD.ID, 

2 BITMAP. 

2 32. 

2 16. 

2 1 ) 


window ID 
bitmap address 
bitmap length (bytes) 
bitmap width, in pixels 
bits/pixel 


GET_BITMAP_ID = BITMAP_ID 
END ! function 


! Subroutine that draws the text 

SUBROUTINE FIXED_TEXT (DOP, D0P_VAR) 

IMPLICIT INTEGER*4(A-Z) 

INCLUDE ^VWSSYSDEF’ 

! Declare the GET.BITMAP_ID function 
INTEGER*4 GET.BITMAP^ID 
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! Associate the predefined structure w/ DOP 
RECORD /DOP.STRUCTURE/ DOP 

! Build the Variable Block 
STRUCTURE /VARIABLE^BLOCK/ 

INTEGER*2 OFFSET.Xl 
INTEGER*2 OFFSET.Yl 

INTEGER*2 0FFSET_X2 
INTEGER*2 0FFSET_Y2 

END STRUCTURE ! Variable block 


! Associate the structure with the DOP 
RECORD /VARIABLE.BLOCK/ DOP.VAR 


! Load the values 

DOP.DOP$W_ITEM^TYPE = DOP$C_DRAW_FIXED_TEXT 
D0P.D0P$W_0P_C0UNT = 2 
DOP.DOP$L^BITMAP^ID = GET_BITMAP^ID() 


DOP.DOP$W_TEXT_HEIGHT = 8 
D0P.D0P$W_TEXT3IDTH = 8 
DOP.DOP$W^TEXT.STARTING^X = 
DOP.DOP$W_TEXT.STARTING_Y = 


D0P_VAR.0FFSET_X1 = 8 
D0P^VAR.0FFSET_Y1 = 0 

D0P^VAR.0FFSET_X2 = 0 
DOP^VAR.OFFSET.Y2 = 0 


100 
100 

! reversed in memory 
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function call 


RETURN 

END 
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Draw Lines 

Describes the additional structure needed to draw lines, using specified end 
points. 


Unique block (plot_args) 


DOP$W-PLOT-FILL-HEIGHT 

DOP$W-PLOT-FILL-WIDTH 

DOP$W-PLOT-FILI_PATTERN-Y 

DOP$W-PLOT-FILL-PATTERN-X 


Field 


Use 


DOP$ W_PLOT_FILL -WIDTH 

DOP$ W_PLOT_FILL -HEIGHT 

DOP$W_PLOT_FILL -PATTERN-X 

DOP$W-PLOT-FILL -PATTERN-Y 


If a bitmap_ID is specified in the Common block, this 
field is the width of the line style bitmap. Otherwise, it 
is ignored. 

If a bitmap JD is specified in the Common block, this 
field is the height of the line style bitmap. Otherwise, it 
is ignored. 

If a bitmap_ID is specified in the Common block, 
this field is the X offset into the line style bitmap. 
Otherwise, it is ignored. 

If a bitmap—ID is specified in the Common block, 
this field is the X offset into the line style bitmap. 
Otherwise, it is ignored. 


Variable block (dop—line—array) 


DOP-LINE$W-Y1 

DOP-LINE$W-X1 

DOP-LINE$W-Y2 

DOP-LINE$W-X2 
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Field 

Use 

DOP_UNE$W_Xl 

DOP_UNE$W_Yl 

DOP_UNE$W_X2 

DOP_LINE$W_Y2 

The X coordinate of the starting point of the line 

The Y coordinate of the starting point of the line 

The X coordinate of the end point of the line 

The Y coordinate of the end point of the line 

Variable-Length Constant: dop_line$c_length 


Description 


The Draw Lines operation permits you to draw: 

• A line 

• A series of lines 

• A polygon (a series of connected lines) 

Draw Lines differs from Fill Lines in that it begins drawing at the specified 
starting point, using the bitmap offset specified (if specified). Fill Lines begins 
drawing at the specified starting point revealing the repeated fill pattern that 
is relative to the lower left comer of the screen. 

The width of lines drawn with this operation is always one pixel. The last 
pixel of each line is not drawn. 

Relevant Common Block Fields 

You may specify a bitmap ID in the Common block to indicate a line style 
to be used when drawing a line. If you do, use the fill^pattem^ and 
fill^pattern^y fields of the Unique block to specify an offset into the bitmap 
as a starting point for the line style and use the width and height fields to 
specify the extents of the bitmap to use. 

By default, the system uses a fill pattern of all Is. 

Initializing the Unique Block 

If you specify a bitmap in the Common block, you must specify the bitmap 
offset and extents in the Unique block. If you do not specify a bitmap, the 
Unique block is ignored by a Draw Lines operation. 
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Initializing the Variable Block 

To draw a line, specify the line's two end points in the Variable block of 
the DOP structure. To draw a series of lines (or a polygon), specify the end 
points of all the lines in the Variable block and specify the number of lines 
you wish to draw in the opcount field of the Common block. 

The QDSS bitmap-memory coordinate system uses an X coordinate that 
increases from left to right and a Y coordinate that increases down. For 
example, to access the top left-hand corner of a bitmap in QDSS memory, 
specify a 0 for both the X and Y source coordinates. 


Example 

The following FORTRAN program takes the following steps to draw a 
polygon: 

1. Uses the predefined structure to initialize the fixed portion of the DOP to 
write four lines. 

2. Defines and initializes the Variable portion of the DOP to hold the end 
point coordinates of four connecting lines. 


! Calling program 


SUBROUTINE DELINKS (DOP, DOP^VAR) 
INCLUDE ’VWSSYSDEF’ 


! Associate the predefined structure w/ DOP 
RECORD /DOP.STRUCTURE/ DOP 

! Build the Variable Block 
STRUCTURE /VARIABLE^BLOCK/ 


INTEGER*2 FIRST«LINE_X1 
INTEGER*2 FIRST^LINE.Yl 
INTEGER*2 FIRST.LINE_X2 
INTEGER*2 FIRST_LINE_Y2 


INTEGER*2 SEC0ND_LINE_X1 
INTEGER*2 SEC0ND_LINE.Y1 
INTEGER*2 SEC0ND_LINE_X2 
INTEGER*2 SEC0ND_LINE_Y2 
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INTEGER*2 THIRD_LINE_X1 
INTEGER*2 THIRD_LINE_Y1 
INTEGER*2 THIRD_LINE_X2 
INTEGER*2 THIRD_LINE.Y2 

INTEGER*2 FOURTH^LINE.Xl 
INTEGER*2 F0URTH_LINE^Y1 
INTEGER*2 F0URTH^LINE«X2 
INTEGER*2 F0URTH_LINE_Y2 

END STRUCTURE ! dop.structure 

! Associate the structure with the D0P_VAR address 
RECORD /VARIABLE_BLOCK/ DOP.VAR 

! Load the DRAW_LINE values 
DOP.DOP$W_ITEM_TYPE = DOP$C_DRAW^LINES 
D0P.D0P$W_0P_C0UNT = 4 

D0P^VAR.FIRST_LINE_X1 = 50 
D0P.VAR.FIRST_LINE_Y1 = 50 
D0P^VAR.FIRST^LINE_X2 = 50 
D0P_VAR.FIRST_LINE^Y2 = 75 

D0P_VAR.SEC0ND_LINE_X1 = 50 
D0P_VAR.SEC0ND_LINE_Y1 = 75 
D0P_VAR.SEC0ND^LINE^X2 = 75 
D0P_VAR.SEC0ND_LINE_Y2 = 75 

D0P^VAR.THIRD.LINE_X1 = 75 
D0P_VAR.THIRD_LINE_Y1 = 75 
D0P_VAR.THIRD^LINE^X2 = 75 
D0P_VAR.THIRD_LINE„Y2 = 50 

DOP.VAR.FOURTH.LINE^Xl = 75 
DOP^VAR.FOURTH^LINE.Yl = 50 
D0P_VAR.F0URTH_LINE_X2 = 50 
D0P^VAR.F0URTH_LINE_Y2 = 50 

RETURN 

END 
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Draw Points 

Describes the additional DOP structure needed to draw points to the screen. 


Unique block (plot—args) 


( 


DOP$W_PLOT_FILL_HEIGHT 

DOP$W_PLOT_FILL_WIDTH 

DOP$W_PLOT_FILL_PATTERN_Y 

DOP$W_PLOT_FILL_PATTERN_X 


Field Use 


DOP$W__PLOT_FILL_ If a bitmap ID is specified in the Common block, this field 

WIDTH is the width of the bitmap. Otherwise, it is ignored. 

DOP$W_JPLOT_FILL_ If a bitinap ID is specified in the Common block, this field 

HEIGHT is the height of the bitmap. Otherwise, it is ignored. 

DOP$W__PLOT_FILL__ If a bitmap ID is specified in the Common block, this field 

PATTERN_X is the X offset into the bitmap. Otherwise, it is ignored. 


DOP$W_PLOT_FILL_ If a bitmap ID is specified in the Common block, this field 

PATTERN_Y is the X offset into the bitmap. Otherwise, it is ignored. 


Variable Block (dop_point—array) 



Field Use 

DOP_POINT$W-_X The X coordinate of the point to draw 

DOPJ’OINTSW—Y The Y coordinate of the point to draw 


Variable-Length Constant: dop__draw_points$c-_Jength 
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Description 


The Draw Points operation permits you to draw a point, a series of points, or 
a series of points that correspond to a specified pattern to the screen. 

Relevant Common Block Fields 

You may specify a bitmap ID in the Common block to indicate a pattern 
to be used when drawing a point or a series of points. If you do, use the 
fill ^pattern—X and fill—pattern^y fields of the Variable block to specify an 
offset into the bitmap as a starting point for the pattern and use the width 
and height fields to specify the extents of the bitmap to use. 

The pattern is incremented 1 pixel/point and is repeated when the width is 
reached. This is useful for drawing a thin patterned curve. 

By default, the system uses a fill pattern of all Is. 

Initializing the Variable Block 

To draw a point, specify the X and Y coordinates of the point in the Variable 
block. To draw a series of points, specify the X and Y coordinates of all the 
points in the Variable block and specify the number of points you wish to 
draw in the opcount field of the Common block. 

The QDSS bitmap-memory coordinate system uses an X coordinate that 
increases from left to right and a Y coordinate that increases down. For 
example, to access the top left-hand comer of a bitmap in QDSS memory, 
specify a 0 for both the X and Y source coordinates. 


Example 

The following FORTRAN example draws three points to the screen: 


! Calling program 


SUBROUTINE DRAW.POINT (DOP. DOP^VAR) 

INCLUDE ’VWSSYSDEF’ 

! Associate the predefined structure w/ DOP 
RECORD /DOP.STRUCTURE/ DOP 
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! Build the Variable Block 
STRUCTURE /VARIABLE_BLOCK/ 

INTEGER*2 FIRST_POINT^X 
INTEGER*2 FIRST_POINT_Y 

INTEGER*2 SECOND.POINT.X 
INTEGER*2 SECOND.POINT^Y 

INTEGER*2 THIRD_POINT.X 
INTEGER*2 THIRD_POINT_Y 

END STRUCTURE ! dop_structure 

! Associate the structure with the DOP.VAR address 
RECORD /VARIABLE_BLOCK/ DOP^VAR 

! Load the DRAW_POINT values 
DOP.DOP$W_ITEM_TYPE = DOP$C_DRAW_POINTS 
D0P.D0P$W_0P_C0UNT = 3 

DOP_VAR.FIRST_POINT_X = 5 
DOP.VAR.FIRST^POINT.Y = 5 

D0P_VAR.SEC0ND_P0INT_X = 5 
D0P_VAR.SEC0ND_P0INT_Y = 25 

DOP_VAR.THIRD_POINT_X = 25 
DOP_VAR.THIRD.POINT_Y = 25 

RETURN 

END 
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Draw Variable Text 

Describes the additional DOP structure needed to draw text of variable width 
to the screen. 


Unique Block (text—args) 


DOP$W_TEXT_WIDTH 

DOP$W_TEXT_HEIGHT 

DOP$W_TEXT_STARTING_Y 

DOP$W_TEXT_STARTING_X 


Field 

Use 

DOP$W_TEXT_HEIGHT 

Height of each character, in pixels; this value is constant 
for each font 

DOP$W_TEXT_WIDTH 

Ignored for variable-width fonts 

DOP$W_TEXT_STARTING_X 

The viewport-relative X coordinate for the starting position 
of the text on the screen 

DOP$W_TEXT_STARTING_Y 

The viewport-relative Y coordinate for the starting position 
of the text on the screen 


Variable Block (dop_vtext_array) 


DOP_VTEXT$W_OFFSET_Y 

DOP_VTEXT$W_OFFSET_X 


DOP_VTEXT$W_WIDTH 
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Field 

Use 

DOP_FrEXT$W_OFFSET_X 

The X coordinate of the offset into the font where a specific 
character is located 

DOP_FrEXT$W_OFFSET_Y 

The Y coordinate of the offset into the font where a specific 
character is located 

DOP_VTEXT$W_WIDTH 

Width of the specified character 

Variable-Length Constant: dop—vtext$cJength 


Description 

The Draw Variable Text operation permits you to write variable-width text to 
the screen. 


To draw scaled, rotated, or differently spaced text, use the Move/Rotate 
DOP. 

Relevant Common Block Fields 

To draw variable-width text to the screen, you must first load a bitmap 
that contains a variable-width font from processor memory to the offscreen 
bitmap memory. You load a bitmap using the UISDC$LOAD-_BITMAP 
routine. This routine returns a bitmap ID that must be loaded in the 
bitmap—[D field of the Common block in order for this operation to succeed. 
(See Section 5.7 for details about loading bitmaps.) 

Initializing the Unique Block 

The Unique block describes both the height of the specified font and the 
position to start writing on the screen. The width field is ignored for this 
operation. Note that when writing text, the position you specify as the 
starting point is the upper left-hand corner of the first character (provided the 
character height is specified as a positive number). This is unlike specifying 
an area, where the starting point is the lower left-hand corner. 

Initializing the Variable Block 

The Variable block indicates which character to write by specifying an offset 
into the font and specifies the width of the character. 

The QDSS bitmap-memory coordinate system uses an X coordinate that 
increases from left to right and a Y coordinate that increases down. For 
example, to access the top left-hand comer of a bitmap in QDSS memory, 
specify a 0 for both the X and Y source coordinates. 
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Example 

The following FORTRAN program writes three characters of text to the 
screen (the word LIP) by taking the following steps: 

1. Creates a 3-letter bitmap — P L I (using a function). 

2. Loads the bitmap, using UISDC$LOAD_BITMAP. 

3. Specifies an opcount of 3. 

4. Initializes the Unique block with a starting position of (100,100). 

5. Initializes the Variable block with the offsets of the three characters (in 
the proper order) and their respective widths. 

Note that the specified offset values seem reversed. This is because of the 
way VAX memory loads the bitmap; the I is loaded at (0,0). 


! Calling program 


! Function that defines 
! and loads the bitmap (font) 

INTEGER*4 FUNCTION GET_BITMAP_ID ! window ID 

! Declare the storage 
IMPLICIT INTEGER*4(A-Z) 

COMMON /WINDOW/ WD_ID. VD_ID 
INTEGER*4 BITMAP_ID 
INTEGER*2 BITMAP(16) 

! Load the bitmap values 
BITMAP(l) = ’784E’X 
BITMAP(2) = ’4844’X 
BITMAP(3) = ’4844’X 
BITMAP(4) = *7844’X 
BITMAP(5) = ’0844’X 
BITMAP(6) = ’0844’X 
BITMAP(7) = ’0844^X 
BITMAP(8) = ’09CE’X 

! Load the bitmap from buffer to QDSS memory 
BITMAP_ID = UISDC$L0AD.BITMAP (WD^ID, ! window ID 
2 BITMAP, ! bitmap address 

2 32, ! bitmap length (bytes) 

2 16, ! bitmap width, in pixels 

2 1) I bits/pixel 
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GET_BITMAP_ID = BITMAP_ID 
END ! function 

! Subroutine that draws the text 

SUBROUTINE VAR.TEXT (DOP, DOP.VAR) 

IMPLICIT INTEGER*4(A-Z) 

INCLUDE ’VWSSYSDEF* 

! Declare the GET_BITMAP_ID function 
INTEGER*4 GET_BITMAP_ID 

! Associate the predefined structure w/ DOP 
RECORD /DOP.STRUCTURE/ DOP 

! Build the Variable Block 
STRUCTURE /VARIABLE.BLOCK/ 

INTEGER*2 OFFSET^Xl 
INTEGER*2 OFFSET.Yl 
INTEGER*2 WIDTHl 

INTEGER*2 0FFSET^X2 
INTEGER*2 0FFSET_Y2 
INTEGER*2 WIDTH2 

INTEGER*2 OFFSET^XS 
INTEGER*2 OFFSET.YS 
INTEGER*2 WIDTHS 

END STRUCTURE ! Variable block 

! Associate the structure with the DOP 
RECORD /VARIABLE_BLOCK/ DOP.VAR 

! Load the values 

DOP.DOP$W_ITEM^TYPE = DOP$C_DRAW_VAR_TEXT 
D0P.D0P$W_0P_C0UNT = 3 

DOP.DOP$L.BITMAP_ID = GET.BITMAP.IDO ! function call 

DOP.DOP$W_TEXT.HEIGHT = 8 
DOP.DOP$W_TEXT.STARTING_X = 100 
DOP.DOP$W^TEXT_STARTING_Y = 100 

D0P_VAR.0FFSET_X1 = 5 ! reversed in memory 

D0P_VAR.0FFSET.Y1 =0 ! 'L’ 

DOP.VAR.WIDTHl = 5 

D0P.VAR.0FFSET^X2 =0 ! ’I’ 

D0P_VAR.0FFSET_Y2 = 0 
D0P_VAR.WIDTH2 = 5 




5-50 Using Drawing Operation Primitives 

Draw Variable Text 


July 1987 


D0P_VAR.0FFSET_X3 =10 ! ’P’ 

D0P.VAR.0FFSET_Y3 = 0 
D0P_VAR.WIDTH3 = 6 

RETURN 

END 
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Fill Lines 

Describes the additional structure needed to draw lines, using a specified 
bitmap pattern. 


Unique Block (plot_args) 


DOP$W_PLOT_FILL -HEIGHT 

DOP$W_PLOT_FILL_WIDTH 

DOP$W_PLOT_FILL _PATTERN_Y 

DOP$W_PLOT_FILL_PATTERN_X 


Field 

Use 

DOP$W_PLOT_FILL_WIDTH 

DOP$ W_PLOT_FILL -HEIGHT 

DOP$ W-PLOT-FILL -PATTERN-X 

DOP$ W-PLOT-FILL -P ATTERN-Y 

Width of fill pattern (from offscreen bitmap), in bits; 
bitmap is identified in bitmap—ID field 

Height of fill pattern (from offscreen bitmap), in bits; 
bitmap is identified in bitmap—ID field 

The X coordinate in the bitmap from which to base 
the fill pattern; bitmap is identified in bitmap—ID field 

The Y coordinate in the bitmap from which to base 
the fill pattern; bitmap is identified in bitmap—ID field 


Variable Block (dop_line_array) 


DOP-LINE$W-Y1 

DOP-LINE$W-X1 

DOP-LINE$W-Y2 

DOP-LINE$W-X2 
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Field 

Use 

DOP_LINE$W_Xl 

DOP_LINE$W_Yl 

DOP_LINE$W_X2 

DOP_LINE$W_Y2 

The X coordinate of the starting point of the line 

The Y coordinate of the starting point of the line 

The X coordinate of the end point of the line 

The Y coordinate of the end point of the line 

Variable-Length Constant: dop—line$c_length 


Description 


The Fill Line operation permits you to draw patterned lines by associating 
the lines with a bitmap pattern. Fill Lines differs from Draw Lines in that 
it associates the specified bitmap pattern with the whole screen area and 
"reveals" the pattern when it draws a line. Draw Lines draws the line, using 
the specified pattern. 

NOTE: This operation is restricted to drawing horizontal lines. This 
restriction may be lifted in a future release. 

Relevant Common Block Fields 

To draw a patterned line to the screen, you must first load a bitmap that 
contains the pattern from processor memory to the offscreen bitmap memory. 
You load a bitmap, using the UISDC$LOAD-_BITMAP routine. This routine 
returns a bitmap ID that must be loaded in the bitmap^D field of the 
Common block for this operation to succeed. (See Section 5.7 for details 
about loading bitmaps.) 

Initializing the Unique Block 

The Unique block describes which portion of the loaded bitmap pattern 
should be used to fill the line. 

Initializing the Variable Block 

To draw a line, specify the line's two end points in the Variable block of the 
DOP structure. To draw a series of lines, specify the end points of all the 
lines in the Variable block and specify the number of lines you wish to draw 
in the opcount field of the Common block. 

The QDSS bitmap-memory coordinate system uses an X coordinate that 
increases from left to right and a Y coordinate that increases down. For 
example, to access the top left-hand comer of a bitmap in QDSS memory, 
specify a 0 for both the X and Y source coordinates. 
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Example 


The following FORTRAN program takes the following steps to draw a 
filled line: 

1. Loads a bitmap pattern using UISDC$LOAD_BlTMAP. 

2. Specifies DOP$C_FILL—LINES in the item—type field. 

3. Defines and initializes the Variable portion of the DOP to hold the 
endpoint coordinates of the line. 

! Calling program 


! Function that defines 
! and loads the bitmap 

INTEGER*4 FUNCTION GET_BITMAP_ID ! window ID 

! Declare the storage 
IMPLICIT INTEGER*4(A-Z) 

COMMON /WINDOW/ WD_ID. VD_ID 
INTEGER*4 BITMAP.ID 
INTEGER*2 BITMAP(16) 

! Load the bitmap values 
BITMAP(l) = ’AAAA’X 
BITMAP(2) = ’5555’X 
BITMAP(3) = ’AAAA’X 
BITMAP(4) = ’5555’X 
BITMAP(5) = ’AAAA’X 
BITMAP(6) = ’5555’X 
BITMAP(7) = ’AAAA’X 
BITMAP(8) = ’5555’X 
BITMAP (9) = ’AAAA’X 
BITMAP(10) = ’5555’X 
BITMAP(ll) = ’AAAA’X 
BITMAP(12) = ’5555’X 
BITMAPdS) = ’AAAA’X 
BITMAP(14) = ’5555’X 
BITMAP(15) = ’AAAA’X 
BITMAP(16) = ’5555’X 
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! Load the bitmap from buffer 
BITMAP.ID = UISDC$LOAD_BITMAP 
2 
2 
2 
2 

GET^BITMAP.ID = BITMAP.ID 
END ! function 

! Subroutine that draws the 1 

SUBROUTINE F.LINE (DOP, D0P_V. 

IMPLICIT INTEGER*4(A-Z) 

INCLUDE ’VWSSYSDEF’ 

! Declare the GET_BITMAP_ID f 
INTEGER*4 GET_BITMAP„ID 

! Associate the predefined fixed structure w/ DOP 
RECORD /DOP.STRUCTURE/ DOP 

! Associate the predefined variable structure w/ D0P_VAR 
RECORD /DOP.LINE^ARRAY/ D0P_VAR 

! Load the FILL_LINE values 
PARAMETER DOP$C_FILL_LINE = 5 
DOP.DOP$W_ITEM_TYPE = DOP$C_FILL.LINE 

D0P.D0P$W_0P^C0UNT = 1 

DOP.DOP$L_BITMAP^ID = GET_BITMAP_ID() ! function call 

DOP.DOP$W_PLOT_FILL_WIDTH = 16 
DOP.DOP$W^PLOT_FILL_HEIGHT = 16 
DOP.DOP$W.PLOT^FILL_PATTERN_X = 0 
DOP.DOP$W^PLOT_FILL_PATTERN.Y = 0 

D0P_VAR.D0P.LINE$W.X1 = 50 
D0P_VAR.D0P.LINE$W.Y1 = 50 
D0P_VAR.D0P.LINE$W_X2 = 150 
D0P_VAR.D0P_LINE$W_Y2 = 50 


to QDSS memory 


(WD^ID, 

BITMAP, 

32, 

16, 

1 ) 


window ID 
bitmap address 
bitmap length (bytes) 
bitmap width, in pixels 
bits/pixel 


ine 

AR) 

unction 


RETURN 

END 
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Fill Point 

Describes the additional DOP structure needed to map a point to a defined 
bitmap. 


Unique Block (plot—args) 


DOP$W_PLOT_FILL-HEIGHT 

DOP$W_PLOT_FILL_WIDTH 

DOP$W_PLOT_FILL_PATTERN_Y 

DOP$W_PLOT_FILL_PATTERN_X 


Field 

Use 

DOP$ W_PLOT_FILL -WIDTH 

DOPSW-PLOT-HLL -HEIGHT 

DOP$ WJPLOT-FILL -PATTERN-X 

DOP$W-PLOT-FILL -PATTERN_Y 

Width of fill pattern (from offscreen bitmap), in bits; 
bitmap is identified in hitmap^D field 

Height of fill pattern (from offscreen bitmap), in bits; 
bitmap is identified in bitmap—ID field 

The X coordinate in the bitmap from which to base 
the fill pattern; bitmap is identified in bitmap—ID field 

The Y coordinate in the bitmap from which to base 
the fill pattern; bitmap is identified in bitmap—ID field 


Variable Block (dop—point—array) 


DOP_POINT$W_Y 


DOR_POINT$W_X 


Field 

Use 

DOP-POINT$W-X 

DOP-POINT$W-Y 

The X coordinate of the point to fill 

The Y coordinate of the point to fill 
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Description 

The Fill Point operation permits you to map individual points that you draw 
to the screen to a bitmap pattern that you specify. If the corresponding bit in 
the bitmap is set, then the point is drawn to the screen (filled); if not, then 
the point is not drawn. 

Relevant Common Block Fields 

To draw patterned points to the screen, you must first load a bitmap that 
contains the pattern from processor memory to the offscreen bitmap memory. 
You load a bitmap, using the UISDC$LOAD_«BITMAP routine. This routine 
returns a bitmap ID that must be loaded in the bitmap^D field of the 
Common block in order for this operation to succeed. (See Section 5.7 for 
details about loading bitmaps.) 

Initializing the Unique Biock 

The Unique block describes which portion of the loaded bitmap pattern 
should be used to determine whether to fill the point. 

initiaiizing the Variabie Block 

The QDSS bitmap-memory coordinate system uses an X coordinate that 
increases from left to right and a Y coordinate that increases down. For 
example, to access the top left-hand corner of a bitmap in QDSS memory, 
specify a 0 for both the X and Y source coordinates. 


Example 

The following FORTRAN program segment draws 90 points in a patterned 
sine curve by taking the following steps: 

1. Creates a bitmap pattern (in a function). 

2. Loads the bitmap, using UISDC$LOADBITMAP. 

3. Specifies an opcount of 90. 

4. Initializes the Unique block. 

5. Uses the SIND and REAL functions to calculate the points on the sine 
curve. 

6. Initializes the Variable block with the points by indexing into the 
Variable block array. 
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! Calling program 


! Function that defines 
! and loads the bitmap 

INTEGER*4 FUNCTION GET_BITMAP_ID ! window ID 

! Declare the storage 
IMPLICIT INTEGER*4(A-Z) 

COMMON /WINDOW/ WD_ID, VD_ID 
INTEGER*4 BITMAP_ID 
INTEGER*2 BITMAP(16) 

! Load the bitmap values 
BITMAP(l) = ’AAAA’X 
BITMAP(2) = ’5555’X 
BITMAP(3) = ’AAAA’X 
BITMAP(4) = ’5555’X 
BITMAP(5) = ’AAAA’X 
BITMAP(6) = ’5555’X 
BITMAP(7) = ’AAAA’X 
BITMAP(8) = ’5555’X 
BITMAP (9) = ’AAAA’X 
BITMAP(10) = ’5555’X 
BITMAP(ll) = ’AAAA’X 
BITMAP(12) = ’5555’X 
BITMAPdS) = ’AAAA’X 
BITMAP(14) = ’5555’X 
BITMAP(15) = ’AAAA’X 
BITMAP(16) = ’5555’X 

! Load the bitmap from buffer to QDSS memory 


BITMAP^ID = UISDC$L0AD3ITMAP 

(WD_ID, 

! window ID 

2 

BITMAP, 

! bitmap address 

2 

32, 

! bitmap length (bytes) 

2 

16, 

! bitmap width, in pixels 

2 

GET_BITMAP_ID = BITMAP^ID 

END ! function 

! * FILL POINT SUBROUTINE * 

1) 

! bits/pixel 


SUBROUTINE F_P0INT (DOP, DOP.VAR) 
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IMPLICIT INTEGER*4(A-Z) 

INCLUDE ’VWSSYSDEF’ 

! Declare the GET_BITMAP_ID function 
INTEGER*4 GETJITMAP^ID 

! Associate the predefined fixed structure w/ DOP 
RECORD /DOP^STRUCTURE/ DOP 

! Build the Variable Block 
STRUCTURE /VARIABLE^BLOCK/ 

INTEGER*2 POINTS(60) 

END STRUCTURE ! dop.structure 
! Associate the structure with the D0P_VAR address 
RECORD /VARIABLE.BLOCK/ DOP.VAR 

! Load the DRAW_POINT values 
DOP.DOP$W_ITEM_TyPE = DOP$C_FILL_POINT 
DOP.DOP$W.OP_COUNT = 90 

DOP.DOP$L.BITMAP.ID = GET_BITMAP_ID() ! function call 
DOP.DOP$W.PLOT_FILL.WIDTH = 16 
DOP.DOP$W.PLOT^FILL.HEIGHT = 16 
DOP.DOP$W.PLOT.FILL.PATTERN_X = 0 
DOP.DOP$W.PLOT_FILL_PATTERN.Y = 0 

! Use a loop to load 30 points 
! set counters 
X = 1 

X. COORD = 1 

Y. COORD = 2 

DO WHILE (X .LE. 91) 

DOP.VAR.POINTS(X.COORD) = X 

DOP.VAR.POINTS(Y.COORD) = SIND(REAL(X)) * 100 

! Increment counters 
X = X + 1 

X. COORD = X.COORD + 2 

Y. COORD = Y.COORD + 2 
END DO 

RETURN 

END 
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Fill Polygon 

Describes the additional DOP structure to create a polygon and fill it with a 
specified pattern. 


Unique block (plot—args) 


DOP$W_PLOT-FILL-HEIGHT 

DOP$W-PLOT-FILL_WIDTH 

DOP$W_PLOT-FILL-PATTERN_Y 

DOP$W_PLOT_FI LL -PATTERN_X 


Field 


Use 


DOP$ W_PLOT_FILL -WIDTH 

DOP$ W_PLOT_FILL -HEIGHT 

DOP$W-PLOT_FILL -PATTERN_X 

DOP$W-PLOT-FILL -PATTERN_Y 


Width of fill pattern (from offscreen bitmap), in bits; 
bitmap is identified in bitmap—ID field. If no bitmap is 
specified, this field is ignored. 

Height of fill pattern (from offscreen bitmap), in bits; 
bitmap is identified in bitmap—ID field. If no bitmap is 
specified, this field is ignored. 

The X coordinate in the bitmap from which to base 
the fill pattern; bitmap is identified in bitmap^D field. 
If no bitmap is specified, this field is ignored. 

The Y coordinate in the bitmap from which to base 
the fill pattern; bitmap is identified in bitmap—ID field. 
If no bitmap is specified, this field is ignored. 


Variable Block (dop—poly—array) 


DOP-POLY$W_LEFT-Y1 

DOP-POLY$W-LEFT-X1 

DOP-POLY$W-LEFT-Y2 

DOP-POLY$W-LEFT-X2 

DOP-POLY$W-RIGHT-Y1 

DOP_POLY$W_RIGHT-X1 
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DOP_POLY$W_RIGHT_Y2 


DOR_POLY$W_RIGHT_X2 


Field 

Use 

DOP_POLY$W_LEFT_Xl 

The X coordinate of the starting point of a line that defines 
the left edge of a polygon 

DOP_POLY$W_LEFT_Yl 

The Y coordinate of the starting point of a line that defines 
the left edge of a polygon 

DOP_POLY$W_LEFT_X2 

The X coordinate of the end point of a line that defines the 
left edge of a polygon 

DOP_POLY$W_LEFT_Y2 

The Y coordinate of the end point of a line that defines the 
left edge of a polygon 

DOP_POLY$W_RIGHT_Xl 

The X coordinate of the starting point of a line that defines 
the right edge of a polygon 

DOP_POLY$W_RIGHT_Yl 

The Y coordinate of the starting point of a line that defines 
the right edge of a polygon 

DOP_POLY$W_RIGHT_X2 

The X coordinate of the end point of a line that defines the 
right edge of a polygon 

DOP_POLY$W_RIGHT_Y2 

The Y coordinate of the end point of a line that defines the 
right edge of a polygon 


Variable-Length Constant; dop_poly$c_length 


Description 

The Fill Polygon operation permits you to write a polygon (more precisely, 
a trapezoid) that is filled with a pattern or a solid color. The trapezoid you 
create must have top and bottom lines that are both parallel and horizontal. 
That is, the Y coordinates of the upper comers must be the same, and the Y 
coordinates of the lower comers must be the same. 

NOTE: Some of these restrictions may be lifted in a future release. 

Relevant Common Block Fields 

To draw a pattern-filled polygon to the screen, you must first load a bitmap 
that contains the pattern with which you wish to fill the polygon from 
processor memory to the offscreen bitmap memory. You load a bitmap, 
using the UISDC$LOAD^BITMAP routine. This routine returns a bitmap 
ID that must be loaded in the bitmap^D field of the Common block. (See 
Section 5.7 for details about loading bitmaps.) 

To fill the polygon with the solid foreground color, specify a bitmap ID of 0 
and omit the Unique block. 
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Initializing the Unique Block 

The Unique block describes which portion of the loaded bitmap pattern 
should be used to fill the polygon. 

Initializing the Variable Block 

The Variable block describes the polygon (more precisely, the trapezoid) by 
specifying the end points of the two lines that are the left and right edges 
of the polygon. Note that the top and bottom lines of the trapezoid must 
be both parallel and horizontal. Therefore the Y coordinates of the upper 
corners must be the same, and the Y coordinates of the lower corners must 
be the same. 

The QDSS bitmap-memory coordinate system uses an X coordinate that 
increases from left to right and a Y coordinate that increases down. For 
example, to access the top left-hand corner of a bitmap in QDSS memory, 
specify a 0 for both the X and Y source coordinates. 


Example 

The following FORTRAN program segment draws a filled polygon by taking 
the following steps: 

1. Creates a bitmap pattern (in a function). 

2. Loads the bitmap, using UISDC$LOAD_BITMAP. 

3. Specifies an opcount of 1. 

4. Initializes the Unique block. 

5. Initializes the Variable block with the end points of the two sides of the 
polygon. 

! Calling program 

! Function that defines 
! and loads the bitmap 

INTEGER*4 FUNCTION GET^BITMAP.ID ! window ID 

! Declare the storage 
IMPLICIT INTEGER*4(A-Z) 

COMMON /WINDOW/ WD^ID, VD_ID 
INTEGER*4 BITMAP^ID 
INTEGER*2 BITMAP(16) 
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! Load the bitmap values 
BITMAP(l) = ’AAAA’X 
BITMAP(2) = ’5555’X 
BITMAP(3) = ’AAAA’X 
BITMAP(4) = ’5555’X 
BITMAP(5) = ’AAAA’X 
BITMAP(6) = ’5555’X 
BITMAP(7) = ’AAAA’X 
BITMAP(8) = ’5555’X 
BITMAPO) = ’AAAA’X 
BITMAP(10) = ’5555’X 
BITMAP(ll) = ’AAAA’X 
BITMAP(12) = ’5555’X 
BITMAPdS) = ’AAAA’X 
BITMAP(14) = ’5555’X 
BITMAP(15) = ’AAAA’X 
BITMAP(16) = ’5555’X 


! Load the bitmap from buffer 
BITMAP_ID = UISDC$LOAD_BITMAP 
2 
2 
2 
2 


to QDSS memory 
(WD_ID, ! window ID 

BITMAP, ! bitmap address 

32, ! bitmap length (bytes) 

16, ! bitmap width, in pixels 

1) ! bits/pixel 


GET_BITMAP_ID = BITMAP_ID 
END ! function 


! Subroutine that draws the polygon 

SUBROUTINE F.POLYGON (DOP, D0P_VAR) 

IMPLICIT INTEGER*4(A-Z) 

INCLUDE ’VWSSYSDEF’ 

! Declare the GET_BITMAP_ID function 
INTEGER*4 GET_BITMAP_ID 

! Associate the predefined fixed structure w/ DOP 
RECORD /DOP.STRUCTURE/ DOP 

! Associate the predefined variable structure w/ D0P_VAR 
RECORD /D0P_P0LY_ARRAY/ D0P_VAR 


! Load the POLYGON values 
DOP.DOP$Vlf_ITEM_TYPE = DOP$C_FILL_POLYGON 

D0P.D0P$W_0P_C0UNT = 1 
DOP.DOP$L_BITMAP_ID = GET_BITMAP_ID() 


! function call 
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DOP.DOP$W_PLOT_FILL_WIDTH = 
DOP.DOP$W_PLOT_FILL_HEIGHT ^ 
DOP.DOP$W_PLOT_FILL_PATTERN. 
OOP.DOP$W_PLOT_FILL_PATTERN. 

D0P_VAR.D0P_P0LY$W_LEFT_X1 ^ 
D0P_VAR.D0P_P0LY$W_LEFT_Y1 ^ 
D0P_VAR.D0P_P0LY$W_LEFT_X2 ^ 
D0P_VAR.D0P_P0LY$W_LEFT_Y2 ^ 

D0P_VAR.D0P_P0LY$W_RIGHT_X1 
DOP.VAR.D0P_P0LY$W_RIGHT_Y1 
DOP.VAR. D0P_P0LY$W_RIGHT_X2 
D0P_VAR.D0P_P0LY$W_RIGHT_Y2 

RETURN 

END 


16 
^ 16 
.X = 0 
.Y = 0 

• 10 
^ 10 
^ 50 
■ 100 

= 150 
= 10 
= 100 
= 100 
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Move Area 

Describes the additional DOP structure needed to move (copy) a rectangular 
area on the screen from one point to another. 


Unique Block 

The Unique block is not relevant to this operation 


Variable Block (dop_move_array) 


DOP_MOVE$W_X_SOURCE 

DOP_MOVE$W_FILLER 

DOP_MOVE$W_WIDTH 

DOP_MOVE$W_Y_SOURCE 

DOP_MOVE$W_X_TARGET 

DOP_MOVE$W_HEIGHT 


DOP_MOVE$W_Y_TARGET 


Field 


Use 


DOP_MOVE$W_nLLER 

DOP_MOVE$W_X_SOURCE 

DOP_MOVE$W_Y_SOURCE 

DOP_MOVE$W_WIDTH 

DOP_MOVE$W_HEIGHT 

DOP_MOVE$W_X_TARGET 

DOP_MOVE$W_Y_TARGET 


Reserved for use by DIGITAL 

The X coordinate of the lower left-hand corner of the 
source area (area to be moved) 

The Y coordinate of the lower left-hand corner of the 
source area 

Width of the area to be moved, in pixels 
Height of the area to be moved, in pixels 

The X coordinate of the lower left-hand comer of 
the target area (the area to which the source area is 
moved) 

The Y coordinate of the lower left-hand comer of the 
target area 


Variable-Length Constant: dop_move$c_-length 
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Description 


The Move Area operation permits you to move (copy) a rectangular area 
from one point to another, either on the screen or in offscreen memory. 

Relevant Common Block Fields 

The default writing mode that is loaded into the Common block (from the 
ATB) during allocation is overlay mode. When moving areas, you want to use 
COPY mode. To load the UIS$_MODE_COPY value into the writing^mode 
field of the Common block: modify the ATB before allocating using the 
UIS$SET_WRITING-JvlODE routine, or load the field with the value 
directly, using the predefined offsets. 

The non-UIS environment writing mode that corresponds to COPY is the 
WRIT$C—S mode (source only). 

Initializing the Variable Block 

To move an area, you must specify the coordinates that define the lower 
left-hand corner of the rectangle you wish to move (source area), the height 
and width of the area, and the coordinates that define the lower left-hand 
corner of the area to which you wish to move it (target area). 


Example 

The following FORTRAN program draws fixed text to the screen at the point 
(100,100). It then moves (copies) an 8-pixel by 16-pixel rectangle containing 
the text from (100,100) to (50,50). 

In the Move Area DOP, the source rectangle coordinates are (100,93). This 
is because when text is written to a specified point on the screen (that is, 
100,100) the point is considered to be the upper left-hand corner of the text 
— but for Move Area you must specify the lower left-hand corner of the 
rectangle. 

The full calling program is shown to clarify the example. 
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PROGRAM MOVE.TEXT 
IMPLICIT INTEGER*4(A-Z) 
INCLUDE ’UISENTRY’ 

INCLUDE ’UISUSRDEF’ 

INCLUDE ’VWSSYSDEF’ 

COMMON /WINDOW/ WD_ID, VD.ID 


! Create a display and window 
VD.ID = UIS$CREATE_DISPLAY (0.0,0.0, 

2 50.0,50.0, 

2 15.0,15.0) 


lower left corner 
upper right corner 
width & height 


WD_ID = UIS$CREATE_WINDOW (VD_ID, 

2 ’SYS$WORKSTATION*, 

2 'DOP Drawing Window’) 


! display ID 
! device name 
! window banner 


! Allocate the DOP for DRAW.LINES 
SIZE = (2 * DOP.FTEXT$C_LENGTH) 

DOPl = UISDC$ALLOCATE_DOP (WD_ID, ! window ID 

2 SIZE, ! variable portion size, in bytes 

2 0) ! default ATB number 

! Call the FIXED_TEXT subroutine 
CALL SUB^FIXED.TEXT (y.VAL(DOPl) . 

2 %VAL(D0P1+D0P$C_LENGTH)) 


! Queue the DOP asynchronously 
CALL UISDC$qUEUE_DOP (WD_ID, 

2 y.VAL(DOPl)) 


1 Allocate the DOP for MOVE_AREA 
SIZE = DOP.MOVE$C_LENGTH 

D0P2 = UISDC$ALLOCATE_DOP (WD_ID, 

2 SIZE, 

2 1 ) 


! Queue the DOP asynchronously 
CALL UISDC$QUEUE_DOP (WD_ID, 

2 yoVAL(DOP2)) 


! window ID 

! DOP address, by value 


! default ATB 
! modified ATB 
COPY) ! new mode 


window ID 

size, in bytes 

number of modified ATB 


^LENGTH)) 

! window ID 

! DOP address, by value 


! Modify the writing mode in ATB 
CALL UIS$SET3RITING_M0DE (VD.ID, 

2 0 , 

2 1 , 

2 UIS$C_M0DE. 


! Call the MOVE^AREA subroutine 
CALL SUB.MOVE^AREA (yoVAL(DOP2) , 

2 yoVAL(DOP2+DOP$C 


CALL SYS$HIBER() 
END 
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! * BITMAP FUNCTION * 

INTEGER*4 FUNCTION GET_BITMAP_ID ! window ID 

! Declare the storage 
IMPLICIT INTEGER*4(A-Z) 

COMMON /WINDOW/ WD.ID, VD_ID 
INTEGER*4 BITMAP^ID 
INTEGER*2 BITMAP(16) 

! Load the bitmap values 
BITMAP(l) = »423E’X 
BITMAP(2) = *4208’X 
BITMAP(3) = ’4208’X 
BITMAP(4) = *4208’X 
BITMAP(5) = *7E08»X 
BITMAP(6) = ’4208’X 
BITMAP(7) = »4208’X 
BITMAP(8) = »4208»X 

! Load the bitmap from 
BITMAP.ID = UISDC$LOAD 
2 
2 
2 
2 

GET_BITMAP^ID = BITMAP.ID 
END ! function 

! * DRAW FIXED TEXT SUBROUTINE * 

SUBROUTINE SUB_FIXED^TEXT (DOP, DOP.VAR) 

IMPLICIT INTEGER*4(A-Z) 

INCLUDE ’VWSSYSDEF’ 

! Declare the GET_BITMAP_ID function 
INTEGER*4 GETJITMAP_ID 

! Associate the predefined structure w/ DOP 
RECORD /DOP.STRUCTURE/ DOP 

! Build the Variable Block 
STRUCTURE /VARIABLE^BLOCK/ 

INTEGER*2 OFFSET.Xl 
INTEGER*2 OFFSET.Yl 


buffer to QDSS memory 
BITMAP (WD^ID, ! window ID 

BITMAP, ! bitmap address 

32, ! bitmap length (bytes) 

16, ! bitmap width, in pixels 

1) ! bits/pixel 






July 1987 


5-68 Using Drawing Operation Primitives 

Move Area 


INTEGER*2 0FFSET_X2 
INTEGER*2 0FFSET_Y2 

END STRUCTURE ! Variable block 

! Associate the Variable block w/ address 
RECORD /VARIABLE_BLOCK/ D0P_VAR 

! Load the values 

DOP.DOP$W_ITEM_TYPE = DOP$C_DRAW_FIXED_TEXT 
D0P.D0P$W_0P_C0UNT = 2 

DOP.DOP$L_BITMAP_ID = GET_BITMAP_ID() ! function call 

DOP.DOP$W_TEXT_HEIGHT = 8 
DOP.DOP$W_TEXT_WIDTH = 8 
DOP.DOP$W_TEXT_STARTING_X = 100 
D0P.D0P$W_TEXT_STARTING_Y = 100 

D0P_VAR.0FFSET_X1 = 8 ! reversed in memory 

D0P_VAR.0FFSET_Y1 = 0 

D0P_VAR.0FFSET_X2 = 0 
D0P_VAR.0FFSET_Y2 = 0 

RETURN 

END 

! * MOVE AREA SUBROUTINE * 

SUBROUTINE SUB_MOVE_AREA (DOP,D0P_VAR) 

INCLUDE ’VWSSYSDEF’ 

! Associate the predefined fixed structure w/ DOP 
RECORD /DOP.STRUCTURE/ DOP 

! Associate predefined Variable Block w/ D0P_VAR 
RECORD /D0P_M0VE_ARRAY/ D0P_VAR 

! Load the MOVE AREA values 
DOP.DOP$W_ITEM_TYPE = D0P$C_M0VE_AREA 
D0P.D0P$W_0P_C0UNT = 1 

D0P_VAR.D0P_M0VE$W_X_S0URCE = 100 
D0P_VAR.D0P_M0VE$W_Y_S0URCE = 93 
DOP_VAR.DOP_MOVE$W_WIDTH = 16 
DOP_VAR.DOP_MOVE$W_HEIGHT = 8 
DOP_VAR.DOP_MOVE$W_X_TARGET = 50 
DOP_VAR.DOP_MOVE$W_Y_TARGET = 50 

RETURN 
END 


!text is written in 
! negative direction 
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Move/Rotate Area 

Describes the additional DOP structure to move and rotate an area on the 
screen to a specified angle (vector) and scale. 


Unique Block 

The Unique block is not relevant to this operation. 


Variable block (dop—move_r—array) 


DOP_MOVE_R$W_X_SOURCE 

DOP_MOVE_R$W_FILLER 

DOP_MOVE_R$W_WIDTH 

DOP_MOVE_R$W_Y_SOURCE 

DOP_MOVE_R$W_X_TARGET 

DOP_MOVE_R$W_HEIGHT 

DOP_MOVE_R$W_X_TARGET_VEC1 

DOP_MOVE_R$W_Y_TARGET 

DOP_MOVE_R$W_L _TARGET_VEC1 

DOP_MOVE_R$W_Y_TARGET_VEC1 

DOP_MOVE_R$W_Y_TARGET_VEC2 

DOP_MOVE_R$W_X_TARGET_VEC2 


DOP_MOVE_R$W_L_TARGET_VEC2 


I 
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Field 


Use 


DOP_MOVE_R$W_nLLER 

DOP_MOVE_R$W_X_SOURCE 


DOP_MOVE_R$W_Y_SOURCE 


DOP_MOVE_R$W_WIDTH 

DOP_MOVE_R$W_HEIGHT 

DOP_MOVE_R$W_X_TARGET 


DOP_MOVE_R$W_Y_TARGET 

DOP_MOVE_R$W_X_TARGET_ 

VECl 


DOP_MOVE_R$W_Y_TARGET_ 

VECl 

DOP_MOVE_R$W_L_TARGET_ 

VECl 

DOP_MOVE_R$W_X_TARGET_ 

VEC2 


DOP_MOVE_R$W_Y_TARGET_ 

VEC2 

DOP_MOVE_R$W_L _TARGET_ 
VEC2 


Reserved for use by DIGITAL 

The X coordinate of the lower left-hand corner of 
the source area (area to be moved); if a bitmap_ID 
is specified in the Common block, this coordinate 
is relative to the bitmap — otherwise it is viewport 
relative 

The Y coordinate of the lower left-hand comer of 
the source area; if a bitmap_ID is specified in the 
Common block, this coordinate is relative to the 
bitmap — otherwise it is viewport relative 

Height of the area to be moved, in pixels 

Width of the area to be moved, in pixels 

The X coordinate of the lower left-hand corner of 

the target area (the area to which the source area is 

moved) 

The Y coordinate of the lower left-hand comer of the 
target area 

The X coordinate of the end point of vector 1 The 
previously specified comer coordinates are used as 
the starting point; used to determine the degree of 
rotation 

The Y coordinate of the end point of vector 1 

The length of vector 1; determines the degree of 
scaling 

The X coordinate of the end point of vector 2; the 
previously specified corner coordinates are used as 
the starting point; the vector is used to determine the 
degree of rotation 

The Y coordinate of the end point of vector 1 

The length of vector 2; determines the degree of 
scaling 


Description 

The Move Rotate Area operation permits you to move (copy) a rectangular 
area from one point to another (either on the screen or in offscreen memory) 
and permits you to rotate and scale the moved copy. 
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This operation also permits you to move/rotate a rectangular area of a 
bitmap identified by the bitmap ID field. 

NOTE: If the source is viewport-relative, the viewport must be unobscured 
and defined as one region for this operation to work properly. This 
restriction does not apply when the bitmap ID is specified. 

NOTE: You must specify a value for all the vector fields even if you desire 
no scaling, otherwise, your results return undefined. 

Relevant Common Block Fields 

If you specify the bitmap ID in the bitmap ID field of the Common block, the 
the x^ource and y^ource fields of the Variable length block are considered 
offsets into the bitmap and the area you move/rotate is from the bitmap. A 
typical use of this feature is to move, rotate, and/or scale text. 

The default writing mode that is loaded into the Common block (from the 
ATB) during allocation is overlay mode. When moving areas, you want to use 
COPY mode. To load the UIS$_MODE_COPY value into the writing mode 
field of the Common block, either modify the ATB before allocating using 
the UIS$SET__WRITING_MODE routine, or load the field with the value 
directly, using the predefined offsets. The non-UIS environment writing 
mode that corresponds to COPY is the WRITSC_S mode (source only). 

Initializing the Variable Block 

To move an area, you must specify the coordinates that define the lower 
left-hand corner of the rectangle you wish to move (source area), the height 
and width of the area, and the coordinates that define the lower left-hand 
corner of the area to which you wish to move it (target area). 

To rotate and scale a moved area, you must specify two vectors. You must 
specify an X and Y value, as well as a length value for each vector. The 
X and Y values are used to specify the angle of rotation; the length value 
specifies the degree of scaling. One vector is related to the X axis the other 
to the Y axis. To determine the proper X and Y values for the vectors, use 
the following formulas: 

For the X axis vector (VECTOR_l): 

X = (original width, in pixels) * COS (desired angle of rotation) 
y = (original width, in pixels) * SIN (desired angle of rotation) 

For the Y axis vector (VECTOR_2): 

X = “(original height, in pixels) * SIN (desired angle of rotation) 
y = (original height, in pixels) * COS (desired angle of rotation) 



July 1987 


5-72 Using Drawing Operation Primitives 
Move/Rotate Area 


The scaling factor is relative to pixels. If the original width of an area is 
100 pixels and you specify a VECTOR^l length of 80, the area will be 
down-scaled by 20%. 

The QDSS bitmap-memory coordinate system uses an X coordinate that 
increases from left to right and a Y coordinate that increases down. For 
example, to access the top left-hand comer of a bitmap in QDSS memory, 
specify a 0 for both the X and Y source coordinates. 


Example 


The following FORTRAN program draws an 11-pixel by 16-pixel rectangle at 
the point (50,50). It then moves (copies) the rectangle to the point (150,150) 
and rotates it 90 degrees. No scaling is specified. 


PROGRAM M0VE_TEXT 
IMPLICIT INTEGER*4(A-Z) 
INCLUDE ’UISENTRY’ 

INCLUDE ’UISUSRDEF’ 

INCLUDE ’VWSSYSDEF* 

INTEGER*4 WD^ID, VD_ID 
COMMON /WINDOW/ WD„ID, VD.ID 


! Create a display and window 
VD_ID = UIS$CREATE.DISPLAY (0.0,0.0, 

2 50.0,50.0, 

2 15.0,15.0) 


lower left corner 
upper right corner 
width & height 


WD_ID = UIS$CREATE_WIND0W (VD.ID, 

2 *SYS$W0RKSTATI0N’, 

2 *D0P Drawing Window’) 


display ID 
device name 
window banner 


! Allocate the DOP for DRAW^LINES 
SIZE = (4 * D0P^LINE$C_LENGTH) 

DOP = UISDC$ALL0CATE^D0P (WD_ID, ! window ID 

2 SIZE, ! variable portion size, in bytes 

2 0) ! default ATB number 


! Call the DRAW LINES subroutine 
CALL D^LINES (•/,VAL(D0P) , 

2 VoVAL (D0P+D0P$C.LENGTH) ) 

! Queue the DOP asynchronously 
CALL UISDC$qUEUE.D0P (WD^ID, 

2 ypVALCDOP)) 


! DOP address, by value 
! Var. block address 


! window ID 

! DOP address, by value 
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( 


! Modify the writing mode in ATB 
CALL UIS$SET_WRITING_MODE (VD.ID, 

2 0. ! default ATB 

2 1, ! modified ATB 

2 UIS$C_M0DE_C0PY) ! new mode 

! Allocate the DOP for MOVE.ROTATE 
SIZE = DOP_MOVE_R$C_LENGTH 
DOPl = UISDC$ALLOCATE_DOP (WD.ID, 

2 SIZE, 

2 1 ) 

! Call the MOVE^ROTATE subroutine 
CALL SUB^MOVE.ROTATE (y.VAL(DOPl) , 

2 yVAL(D0P1+D0P$C_LENGTH)) 

! Queue the DOP asynchronously 

CALL UISDC$QUEUE_DOP (WD_ID. ! window ID 

2 yoVAL(DOPl)) ! DOP address, by value 

CALL SYS$HIBER() 

END 

! * DRAW LINES SUBROUTINE * 

SUBROUTINE D.LINES (DOP, DOP.VAR) 

INCLUDE ’VWSSYSDEF’ 

! Associate the predefined structure w/ DOP 
RECORD /DOP.STRUCTURE/ DOP 

! Build the Variable Block 
STRUCTURE /VARIABLE^BLOCK/ 

INTEGER*2 FIRST^LINE.Xl 
INTEGER*2 FIRST^LINE.Yl 
INTEGER*2 FIRST_LINE.X2 
INTEGER*2 FIRST_LINE^Y2 

INTEGER*2 SECOND.LINE.Xl 
INTEGER*2 SEC0ND_LINE_Y1 
INTEGER*2 SEC0ND.LINE_X2 
INTEGER*2 SEC0ND_LINE_Y2 

INTEGER*2 THIRD.LINE^Xl 
INTEGER*2 THIRD.LINE^Yl 
INTEGER*2 THIRD.LINE^X2 
INTEGER*2 THIRD_LINE_Y2 


window ID 

size, in bytes 

number of modified ATB 
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INTEGER*2 F0URTH_LINE_X1 
INTEGER*2 F0URTH_LINE_Y1 
INTEGER*2 F0URTH_LINE_X2 
INTEGER*2 F0URTH_LINE_Y2 

END STRUCTURE I dop_structure 

! Associate the structure with the D0P_VAR address 
RECORD /VARIABLE.BLOCK/ DOP.VAR 

! Load the DRAW_LINE values 
DOP.DOP$W_ITEM.TYPE = DOP$C_DRAW_LINES 
D0P.D0P$W_0P_C0UNT = 4 

DOP.VAR.FIRST_LINE_X1 = 50 
DOP.VAR.FIRST.LINE.Yl = 50 
DOP.VAR.FIRST.LINE.X2 = 50 
DOP.VAR.FIRST.LINE.Y2 = 65 

DOP.VAR.SECOND.LINE.Xl = 50 
DOP.VAR.SECOND.LINE.Yl = 65 
DOP.VAR.SEC0ND.LINE.X2 = 60 
DOP.VAR.SEC0ND.LINE.Y2 = 65 

DOP.VAR.THIRD.LINE.Xl = 60 
DOP.VAR.THIRD.LINE.Yl = 65 
DOP.VAR.THIRD.LINE.X2 = 60 
DOP.VAR.THIRD.LINE.Y2 = 50 

DOP.VAR.FOURTH.LINE.Xl = 60 
DOP.VAR.FOURTH.LINE.Yl = 50 
DOP.VAR.F0URTH.LINE.X2 = 50 
DOP.VAR.F0URTH.LINE.Y2 = 50 

RETURN 

END 

! * MOVE ROTATE SUBROUTINE * 

SUBROUTINE SUB.MOVE.ROTATE (DOP, DOP.VAR) 

INCLUDE ^VWSSYSDEF’ 

! Associate the predefined fixed structure w/ DOP 
RECORD /DOP.STRUCTURE/ DOP 

! Associate the predefined variable structure w/ DOP.VAR 
RECORD /DOP.MOVE.R.ARRAY/ DOP.VAR 

! Load the values 

DOP.DOP$W.ITEM.TYPE = DOP$C.MOVE.ROTATE.AREA 
DOP.DOP$W.OP.COUNT = 1 
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DOP_VAR.DOP_MOVE_R$W_X_SOURCE = 50 
DOP_VAR.DOP_MOVE_R$W_Y_SOURCE = 50 
D0P_VAR.D0P_M0VE_R$W_WIDTH =11 
D0P_VAR.D0P_M0VE_R$W_HEIGHT = 16 
D0P_VAR.D0P_M0VE_R$W_X_TARGET = 150 
D0P_VAR.D0P_M0VE_R$W_Y_TARGET = 150 
D0P_VAR.D0P_M0VE_R$W_X_TARGET_VEC1 = 
D0P_VAR.D0P_M0VE_R$W_Y_TARGET_VEC1 = 
D0P_VAR.D0P_M0VE_R$W_L_TARGET_VEC1 = 
D0P_VAR.D0P_M0VE_R$W_X_TARGET_VEC2 = 
DOP.VAR.D0P_M0VE_R$W_Y_TARGET_VEC2 = 
D0P_VAR.D0P_M0VE_R$W_L_TARGET_VEC2 = 


(11 * C0SD(90.)) 
(11 * SIHDOO.)) 
11 

(-16 * SINDOO.)) 
(16 * C0SD(90.)) 
16 


RETURN 

END 
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Resume Viewport Activity 

Describes the additional DOP structure needed for a system viewport to 
resume activity on a suspended viewport. 


Unique Block (stop.-.args) 


DOP$L ^DRI VER_>VP-_I D 


Field 

Use 

DOP$L _DRIVER_VP_ID 

The viewport ID associated with the request queue to be 
resumed 


Description 

The Resume Viewport Activity operation resumes activity on a viewport 
that was suspended using the Suspend Viewport Activity DOP (or Suspend 
Viewport Activity QIO function). 

Since the target viewport is suspended, this DOP must be inserted on the 
queue of a viewport that is not suspended. In most cases, the systemwide 
viewport is used to resume suspended viewports. 

Initializing the Unique Block 

The Unique block specifies the viewport ID of the viewport to be resumed. 
You obtain the viewport ID with the Get Viewport ID QIO at viewport 
creation time. 

Initializing the Variable Block 

The QDSS bitmap-memory coordinate system uses an X coordinate that 
increases from left to right and a Y coordinate that increases down. For 
example, to access the top left-hand comer of a bitmap in QDSS memory, 
specify a 0 for both the X and Y source coordinates. 
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Example 


The following FORTRAN program resumes activity on a viewport whose ID 
is passed to the subroutine: 


! Calling Program 


! * RESUME SUBROUTINE * 

SUBROUTINE RESUME (DOP, D0P_VAR, VP_ID) 

INCLUDE ’VWSSYSDEF’ 

! Associate the predefined fixed structure w/ DOP 
RECORD /DOP_STRUCTURE/ DOP 

! Load the value 

DOP.DOP$W_ITEM_TYPE = DOP$C_RESUME 
D0P.D0P$W_0P_C0UNT = 1 
DOP.DOP$L_DRIVER_VP_ID = VP_ID 

RETURN 

END 
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Scroll Area 

Describes the additional DOP structure needed to scroll the screen display. 

Unique Block 

The Unique block is not relevant to this operation 

Variable block (dop^move—array) 


DOP-_MOVE$W_Y__TARGET 


Field Use 

DOP_MOVE$W_FILLER Reserved for use by DIGITAL 

DOP_-MOVE$W_J(—SOURCE The X coordinate of the lower left-hand comer of the 

source area (area to be moved) 

DOP_MOVE$W—Y—SOURCE The Y coordinate of the lower left-hand comer of the 

source area 

DOP—MOVE$W—WIDTH Height of the area to be moved, in pixels 

DOP—MOVE$W—HEIGHT Width of the area to be moved, in pixels 

DOP—MOVESW—X—TARGET The X coordinate of the lower left-hand comer of the target 

area (the area to which the source area is moved) 

DOP—MOVE$W—Y—TARGET The Y coordinate of the lower left-hand comer of the target 

area 

Variable-Length Constant: dop—move$c-length 


DOP-MOVE$W-FILLER 

DOP-MOVE$W-Y-SOURCE 

DOP-MOVE$W-HEIGHT 


DOP-MOVE$W-X-SOURCE 

DOP-MOVE$W-WIDTH 

DOP-MOVE$W-X-TARGET 
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Description 

The Scroll Area operation permits you to move (copy) a rectangular area 
either on the screen or in offscreen memory. It differs from the Move Area 
operation in that it erases (fills with background color) the area specified as 
the source. This operation is typically used for onscreen scrolling. 

Relevant Common Block Fields 

Scroll Area always uses the copy writing mode. It ignores any value currently 
contained in the writing^mode field. 

Initializing the Variable Block 

To scroll an area, you must specify the coordinates that define the lower 
left-hand comer of the rectangle you wish to move (source area), the height 
and width of the area, and the coordinates that define the lower left-hand 
comer of the area to which you wish to move it (target area). 


Example 

The following FORTRAN program scrolls an 11-pixel by 16-pixel rectangle 
from the point (50,50) to the point (50,150): 


PROGRAM SCROLL 
IMPLICIT INTEGER*4(A-Z) 
INCLUDE ’UISENTRY’ 

INCLUDE ’UISUSRDEF’ 

INCLUDE ’VWSSYSDEF’ 

COMMON /WINDOW/ WD_ID, VD^ID 


! Create a display and window 
VD.ID = UIS$CREATE^DISPLAY (0.0,0.0, 

2 50.0,50.0, 

2 15.0,15.0) 


lower left corner 
upper right corner 
width & height 


WD.ID = UIS$CREATE_WIND0W (VD^ID, 

2 ’SYS$W0RKSTATI0N». 

2 'DOP Drawing Window*) 


display ID 
device name 
window banner 


! Allocate the DOP for DRAW_LINES 
SIZE = (4 * D0P_LINE$C_LENGTH) 

DOP = UISDC$ALL0CATE.D0P (WD_ID, 

2 SIZE, 

2 0 ) 


window ID 

variable portion size, in bytes 
default ATB number 
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! Call the DRAW LINES subroutine 
CALL D.LINES C/oVALCDOP) , 

2 ‘/pVAL (D0P+D0P$C_LENGTH) ) 

! Queue the DOP asynchronously 
CALL UISDC$QUEUE.DOP (WD.ID, 

2 %VAL(D0P)) 


! DOP address, by value 
! Var. block address 

! window ID 

! DOP address, by value 


! Modify the writing mode in ATB 
CALL UISSSET^RITING.MODE (VD.ID, 

2 0, ! default ATB 

2 1, ! modified ATB 

2 UIS$C_M0DE.C0PY) ! new mode 


! Allocate the DOP for SCROLL 
SIZE = DOP^MOVE$C_LENGTH 
DOPl = UISDC$ALLOCATE.DOP (WD_ID, 
2 SIZE, 

2 1 ) 


window ID 

size, in bytes 

number of modified ATB 


! Call the M0VE_R0TATE subroutine 
CALL SUB.SCROLL C/.VALCDOPI) , 

2 yoVAL(DOPl+DOP$C^LENGTH)) 


! Queue the DOP asynchronously 

CALL UISDC$QUEUE.DOP (WD_ID, ! window ID 

2 yoVALCDOPl)) ! DOP address, by value 

CALL SYS$HIBER() 


END 


! * DRAW LINES SUBROUTINE * 

SUBROUTINE D.LINES (DOP, DOP^VAR) 

INCLUDE ’VWSSYSDEF* 

! Associate the predefined structure w/ DOP 
RECORD /DOP.STRUCTURE/ DOP 

! Build the Variable Block 
STRUCTURE /VARIABLE.BLOCK/ 

INTEGER*2 FIRST_LINE^X1 
INTEGER*2 FIRST.LINE.Yl 
INTEGER*2 FIRST_LINE_X2 
INTEGER*2 FIRST^LINE^Y2 





July 1987 Using Drawing Operation Primitives 

Scroll Area 


INTEGER*2 SEC0ND_LINE_X1 
INTEGER*2 SECOND.LINE.Yl 
INTEGER*2 SEC0ND^LINE.X2 
INTEGER*2 SEC0ND^LINE_Y2 

INTEGER*2 THIRD.LINE^Xl 
INTEGER*2 THIRD.LINE.Yl 
INTEGER*2 THIRD.LINEJ2 
INTEGER*2 THIRD.LINE^Y2 


INTEGER*2 F0URTH_LINE_X1 
INTEGER*2 F0URTH_LINE^Y1 
INTEGER*2 F0URTH_LINE.X2 
INTEGER*2 F0URTH_LINE_Y2 


END STRUCTURE ! dop_structure 

I Associate the structure with the D0P_VAR address 
RECORD /VARIABLE.BLOCK/ DOP.VAR 


! Load the DRAW^LINE values 
DOP.DOP$W_ITEM_TYPE = DOP$C_DRAW.LINES 
D0P.D0P$W^0P_C0UNT = 4 


DOP.VAR.FIRST.LINE^Xl = 50 
D0P_VAR.FIRST_LINE^Y1 = 50 
D0P_VAR.FIRST_LINE_X2 = 50 
D0P_VAR.FIRST^LINE^Y2 = 65 

DOP.VAR.SECOND^LINE^Xl = 50 
DOP.VAR.SECOND^LINE^Yl = 65 
D0P_VAR.SEC0ND_LINE_X2 = 60 
D0P_VAR.SEC0ND_LINE_Y2 = 65 

D0P_VAR.THIRD^LINE_X1 = 60 
D0P_VAR.THIRD_LINE_Y1 = 65 
D0P_VAR.THIRD_LINE_X2 = 60 
D0P_VAR.THIRD.LINE_Y2 = 50 

D0P.VAR.F0URTH_LINE.X1 = 60 
D0P_VAR.F0URTH_LINE.Y1 = 50 
D0P_VAR.F0URTH_LINE_X2 = 50 
D0P_VAR.F0URTH_LINE_Y2 = 50 


RETURN 

END 


* SCROLL SUBROUTINE * 
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SUBROUTINE SUB.SCROLL (DOP, DOP.VAR) 
INCLUDE *VWSSYSDEF’ 
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! Associate the predefined fixed structure w/ DOP 
RECORD /DOP_STRUCTURE/ DOP 

! Associate the predefined variable structure w/ D0P_VAR 
RECORD /D0P_M0VE_ARRAY/ D0P_VAR 

! Load the values 

DOP.DOP$W_ITEM_TYPE = DOP$C_SCROLL_AREA 
DOP.DOP$W_OP_COUNT = 1 

D0P_VAR.D0P_M0VE$W_X_S0URCE = 50 
D0P_VAR.D0P_M0VE$W_Y_S0URCE = 50 
DOP_VAR.DOP_MOVE$W_WIDTH =11 
DOP_VAR.DOP_MOVE$W_HEIGHT = 16 
DOP_VAR.DOP_MOVE$W_X_TARGET = 50 
DOP_VAR.DOP_MOVE$W_Y_TARGET = 150 

RETURN 

END 
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Start Request Queue 

Describes the additional DOP structure needed for the system viewport to 
restart a stopped request queue on another viewport. 


Unique Block (stop^args) 



DOP$L_DRIVER_VP_ID 



Field 

Use 

DOP$L _DRIVER_VP_ID 

The viewport ID associated with the request queue to be 


started 




Description 

The Start Request Queue operation starts (or restarts) the processing of 
packets on the request queue of the specified viewport. 


Typically, this call is made after the queue has been stopped with the 
Stop operation. Since the target viewport is stopped, this DOP must be 
inserted on the queue of a viewport that is not stopped. In most cases, the 
systemwide viewport is used to start stopped viewports. 

Initializing the Unique Block 

The Unique block specifies the viewport ID of the viewport to be started. 
You obtain the viewport ID with the Get Viewport ID QIO at viewport 
creation time. 

Initializing the Variable Block 

The QDSS bitmap-memory coordinate system uses an X coordinate that 
increases from left to right and a Y coordinate that increases down. For 
example, to access the top left-hand corner of a bitmap in QDSS memory, 
specify a 0 for both the X and Y source coordinates. 
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Example 


The following FORTRAN program starts activity on a viewport whose ID is 
passed to the subroutine: 


! Calling Program 


! * START SUBROUTINE * 

SUBROUTINE START (DOP, DOP.VAR, VP_ID) 

INCLUDE ’VWSSYSDEF’ 

! Associate the predefined fixed structure w/ DOP 
RECORD /DOP_STRUCTURE/ DOP 

! Load the value 

DOP.DOP$W_ITEM_TYPE = DOP$C_START 
D0P.D0P$W_0P_C0UNT = 1 
DOP.DOP$L_DRIVER_VP_ID = VP_ID 

RETURN 

END 
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Stop Request Queue 

Describes the additional DOP structure needed to stop removing entries from 
the specified viewport's request queue. 


Unique Block (stop^args) 


DOP$L_DRIVER>_VP^ID 


Field 

Use 

DOP$L _DRIVER_VP_ID 

The viewport ID associated with the request queue to be 
stopped 


Description 

The Stop Request Queue operation stops processing on the request queue of 
the specified viewport to give the calling process control over the viewport 
bitmap. Stopping a viewport's request queue ensures that no other processes 
will modify the bitmap of the stopped viewport. To guarantee that all 
DOPs previously on the queue are processed, insert this DOP on the 
queue with the Insert DOP QIO or the Execute DOP UISDC routine. The 
distinction between Stop and Suspend is that Stop waits for any DOPs 
already processing to complete before returning control. 

A viewport management task typically uses this operation to change the 
position or occlusion of any viewport in the system (using the Set Viewport 
Region QIO). 

Once the Stop operation is invoked, no further commands can be executed 
from the request queue unless the request queue is explicitly restarted with 
the Start Request Queue QIO, or the Start Request Queue DOP (from a 
viewport other than the stopped one). 

Initializing the Unique Block 

The Unique block specifies the viewport ID of the viewport to be stopped. 
You obtain the viewport ID with the Get Viewport ID QIO at viewport 
creation time. 
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Initializing the Variable Block 

The QDSS bitmap-memory coordinate system uses an X coordinate that 
increases from left to right and a Y coordinate that increases down. For 
example, to access the top left-hand comer of a bitmap in QDSS memory, 
specify a 0 for both the X and Y source coordinates. 


Example 

The following FORTRAN program stops activity on a viewport whose ID is 
passed to the subroutine: 


! Calling Program 


! * STOP SUBROUTINE * 

SUBROUTINE STOP (DOP, DOP.VAR, VP_ID) 

INCLUDE ’VWSSYSDEF’ 

! Associate the predefined fixed structure w/ DOP 
RECORD /DOP.STRUCTURE/ DOP 

! Load the value 

DOP.DOP$W^ITEM_TYPE = D0P$C_ST0P 
D0P.D0P$W^0P^C0UNT = 1 
D0P.D0P$L_DRIVER^VP^ID = VP^ID 


RETURN 

END 





( 
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Suspend Viewport Activity 

Describes the additional DOP structure to suspend activity on a viewport. 


Unique Block (stop_args) 


DOP$L_DRIVER_VP_ID 


Field 

Use 

DOP$L _DRIVER_VP_ID 

The viewport ID associated with the request queue to be 
suspended 


( 



Description 

The Suspend Viewport Activity operation suspends activity on a specified 
viewport. 

Typically, this operation is used to synchronize drawing operations. When 
operations are completed, you can resume activity on the viewport by 
making a call to the Resume QIO, or by invoking the Resume DOP (from a 
viewport other than the stopped one). Suspend and Resume can be thought 
of as the drawing parallels to the CTRL/S and CTRL/Q key functions. 

The distinction between Stop and Suspend is that Stop waits for any DOPs 
already processing to complete before returning control. 

Initializing the Unique Block 

The Unique block specifies the viewport ID of the viewport to be suspended. 
You obtain the viewport ID with the Get Viewport ID QIO at viewport 
creation time. 

Initializing the Variable Block 

The QDSS bitmap-memory coordinate system uses an X coordinate that 
increases from left to right and a Y coordinate that increases down. For 
example, to access the top left-hand corner of a bitmap in QDSS memory, 
specify a 0 for both the X and Y source coordinates. 
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Example 


The following FORTRAN program suspends activity on a viewport whose ID 
is passed to the subroutine: 


! Calling Program 


! * SUSPEND SUBROUTINE * 

SUBROUTINE SUSPEND (DOP, DOP.VAR, VP_ID) 

INCLUDE ’VWSSYSDEF’ 

! Associate the predefined fixed structure w/ DOP 
RECORD /DOP_STRUCTURE/ DOP 

! Load the value 

DOP.DOP$W_ITEM_TYPE = DOP$C_SUSPEND 
D0P.D0P$W_0P_C0UNT = 1 
DOP.DOP$L_DRIVER_VP_ID = VP_ID 

RETURN 

END 
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5.7 UlSDC OOP Interface 

The UISDC DOP interface is provided so that DOPs can be used by applications 
that draw within UIS viewports. The five UISDC routines that make up the interface 
permit an application to: 

• Allocate storage for a DOP — UISDC$ALLOCATE_DOP. 

• Load bitmaps from processor memory into offscreen bitmap memory (for 
subsequent use by text or fill pattern DOPs) — UISDC$LOAD_-BITMAP. 

• Submit DOPs to the request queue for execution — UISDC$EXECUTE_DOP_ 
ASYNCH, UISDC$EXECUTE-.DOP_SYNCH, and UISDCSQUEUE^DOP. 

This section describes each routine. 

How to use UISDC$ ALLOC ATE--DOP to allocate DOPs is described in Section 
5.3.1. 

How to use UISDC$EXECUTE-_DOP-JVSYNCH, UISDC$EXECUTE^DOP-_SYNCH, 
and UISDC$QUEUE—DOP to execute DOPs (and how they differ from one another) 
is described in Section 5.3.2. 

How to use UISDC$LOAD—BITMAP is described below. 
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5.7.1 Loading Bitmaps into Offscreen Memory 

To load a bitmap, use the UISDC$LOAD_BITMAP routine. 

UISDC$LOAD_BITMAP returns a bitmap identifier (a handle) when you specify 
a window ID (in which the bitmap will be used), the bitmap address, the length 
and width of the bitmap, and the number of bits per pixel (more than one on color 
systems). 

There are two ways to use UISDCSLOAD—BITMAP: 

• One causes the bitmap to be copied from the user's buffer into a buffer 
maintained by the driver. When the bitmap is accessed it is copied from the 
driver-maintained buffer into offscreen memory. 

• The other creates a handle (identifier) for the bitmap, but relies on the application 
to supply the bitmap when it is accessed. This second method saves space by 
not loading bitmaps until they are actually accessed. 

To have the driver maintain the bitmap, specify the address of the bitmap in 
process memory as the bitmap address parameter. To access the bitmap in a 
subsequent DOP, load the bitmap^D field of the DOP Common block with the 
bitmap ID returned by Load Bitmap. The system handles the storage of this bitmap. 
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When the system manages bitmap storage, it uses the bitmap glyph as a backing 
store address if it has to swap the bitmap out of offscreen memory. That is, when 
the bitmap is accessed, the system uses the bitmap glyph to swap the bitmap back 
into offscreen memory. 

To dynamically load a bitmap, specify 0 as the bitmap address parameter, but 
still specify the correct length, width, and bits-per-pixel To access the bitmap in a 
subsequent DOP, load the bitmap—lD field of the DOP Common block with the 
bitmap ID returned by LOAD_BITMAP and load the bitmap—glyph field of the 
Common block with the address of the bitmap in processor memory. 

When you specify a bitmap address of 0 and put the true address in the bitmap— 
glyph field, you save system resources. The bitmap is not loaded until it is accessed, 
and the application, not the system, is responsible for saving the bitmap (when it is 
swapped out, it is unknown by the system). 
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UISDC$ALLOCATE_DOP—Allocate Drawing Packet 

Allocates a driver drawing operation primitive (DOP) for a particular display 
window. 


Format 

dop_adc/ress=UISDC$ALLOCATE_DOP wd—id ,size ,atb 


Returns 


VMS Usage: 
type: 
access: 
mechanism: 


address 

longword (unsigned) 
write only 
by value 


Longword value returned as the address of the DOP in the variable dop— 
address or RO (VAX MACRO). LFsed in subsequent execution calls. 

UISDC$ ALLOC ATE _DOP signals all errors; no condition values are 
returned. 


Arguments 


wd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


The window identifier. The wd_id argument is the address of a longword 
that uniquely identifies the display window. This routine associates the 
DOP with a window by loading the viewport-related fields of the Common 
block with the coordinates from the specified window (to determine the 
clipping rectangle). The window identifier is returned to an application at 
viewport creation time. See UIS$CREATE—WINDOW in the MicroVMS 
Workstation Graphics Programming Guide for more information about the 
wd_id argument. 


size 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
modify 
by reference 
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Size of the variable portion of the DOP, in bytes. On input, the size 
argument is the address of a number that defines the requested size of 
the variable portion of the DOP to be allocated. 

On output, it is the size of the variable portion of the DOP that was actually 
allocated. The size allocated may be smaller than the size you request. 
Always use the returned size in subsequent operations. 


atb 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Attribute block number. The atb argument is the address of the attribute 
block which is used to initialize the color, writing—mode, and writing—mask 
fields of the Common block. 
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UISDC$LOAD-BITMAP—Load Bitmap 

Loads a bitmap from processor memory into offscreen memory. 

Format 

£>/fmap_/cHJISDC$LOAD_BITMAP wd—id,bitmap—adr 

,bitmap—len 
, bitmap—width 
,bits—per—pixei 

Returns 

VMS Usage: identifier 
type: iongword (unsigned) 

access: write only 

mechanism: by value 

Longword value returned as the bitmap identifier in the variable bitmap—id 
or RO (VAX MACRO). This value is used in DOP$L_BlTMAP_lD field of 
subsequent driver DOPs. 

UlSDC$LOAD_BlTMAP signals all errors; no condition values are returned. 

Arguments 

wei—id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Display window identifier. The wd_id argument is the address of a 
longword that uniquely identifies a display window. The window identifier 
is returned to an application at viewport creation time. See U1S$CREATE_ 
WINDOW in the MicroVMS Workstation Graphics Programming Guide for 
more information about the wd_id. 

bitmap—adr 

VMS Usage: address 

type: longword (unsigned) 

access: read only 

mechanism: by reference 
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Bitmap address. The bitmap_adr argument is the address of a bitmap 
located in processor memory. 


bitmap—len 
VMS Usage; 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Bitmap length. The bitmap_len argument is the address of the number that 
defines the length of the bitmap in bytes. The length must be a multiple of 2. 


bitmap—width 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


Width of the bitmap. The bitmap-width argument is the address of a 
number that defines the width of the bitmap in pixels. If the width of the 
bitmap is greater than 1024, the bitmap will wrap. Single-plane bitmaps 
must have a width that is a multiple of 16. 


bits—per—pixei 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by reference 


The bits—per—pixel argument is the address of a number that defines the 
number of bits per pixel. Currently, the values 1 and 8 are supported. 


Description 

UISDC$LOAD—BITMAP loads a bitmap that resides in processor memory 
into the bitmap portion of offscreen memory. It returns a bitmap ID for 
the loaded bitmap that can be used in DOPs that require a bitmap ID (fill 
operations and text operations). In those cases, the returned bitmap ID is 
loaded into the DOP$C_BITMAP-_ID field of the Common block. 
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UISDC$EXECUTE_DOP_ASYNCH—Execute Drawing 

Operation Primitive 
Asynchronousiy 


Starts the execution of the specified drawing operation primitive (DOP) in the 
specified display window and returns control to the application immediately. 


Format 

UISDC$EXECUTE_DOP_ASYNCH wd-id ,dop-address ,iosb 


Returns 

UISDC$EXECUTE_DOP_ASYNCH signals all errors; no condition values 
are returned. 


Arguments 


wd—id 


VMS Usage: 
type; 
access: 
mechanism: 


identifier 

longword (unsigned) 
read only 
by reference 


Display window identifier. The wd_id argument is the address of a 
longword that uniquely identifies the display window. The window identifier 
is returned to an application at viewport creation time. See UIS$CREATE_ 
WINDOW in the MicroVMS Workstation Graphics Programming Guide for 
more information about the wd_id argument. 


dop—address 

VMS Usage: vector_byte—unsigned 
type: byte_unsigned 

access: read only 

mechanism: by reference 


DOP. The dop—address argument is the address of an array of bytes that 
comprise the DOP. This address is returned by the U1SDC$ ALLOC ATE _ 
DOP routine. 
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UISDC$EXECUTE_DOP_ASYNCH 


iosb 


VMS Usage: 
type: 
access: 
mechanism: 


cond—value 
longword (unsigned) 
write only 
by reference 


I/O status block. The iosb argument is the address of an I/O status block 
that receives a value indicating that the DOP is queued for execution. The 
IOSB also receives notification when the DOP is completed. 


Description 

UISDC$EXECUTE_DOR_ASYNCH queues the specified DOP for execution 
in the specified window's request queue. The execution is performed 
asynchronously; the DOP is queued for execution, but control is immediately 
returned to the application. You can use the IOSB to determine when the 
DOP has actually completed. 
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UISDC$EXECUTE_DOP_SYNCH—Execute Drawing 

Operation Primitive 
Synchronously 

Executes the specified drawing operation primitive (DOP) in the specified 
display window and returns control to the application. 


Format 

UISDC$EXECUTE_DOP_SYNCH wd-id ,dop-address 


Returns 

UlSDC$EXECUTE_DOP_SYNCH signals all errors; no condition values are 
returned. 


Arguments 


wd—id 


VMS Usage: 
type: 
access: 
mechanism: 


identifier 

longword (unsigned) 
read oniy 
by reference 


Display window identifier. The wd_id argument is the address of a 
longword that uniquely identifies the display window. The window identifier 
is returned to an application at viewport creation time. See UIS$CREATE_ 
WINDOW in the MicroVMS Workstation Graphics Programming Guide for 
more information about the wd_id argument. 


dop—address 

VMS Usage: vector_byte—unsigned 
type: byte_unsigned 

access: read only 

mechanism: by reference 


DOP. The dop_address argument is the address of an array of bytes that 
comprise the DOP. This address is returned by the U1SDC$ ALLOC ATE _ 
DOP routine. 
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UISDC$EXECUTE_DOP-.SYNCH 


Description 

UISDC$EXECUTE-«DOP_SYNCH queues the specified DOP for execution 
on the specified window's request queue. The execution is performed 
synchronously; the DOP is queued for execution, and EXECUTE _DOP- 
SYNCH waits until the operation is completed before returning control to the 
application. 
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UISDC$QUEUE_DOP—Queue Drawing Operation Primitive 

Queues the specified drawing operation primitive for execution in the 
specified window and returns control to the application. 


Format 

UISDC$QUEUE_DOP wd—id ,dop—address 


Returns 

UISDC$QUEUE_DOP signals all errors; no condition values are returned. 


Arguments 


wd—id 


VMS Usage; 
type: 
access: 
mechanism: 


identifier 

iongword (unsigned) 
read oniy 
by reference 


Display window identifier. The wd_id argument is the address of a 
Iongword that uniquely identifies the display window. The window identifier 
is returned to an application at viewport creation time. See UIS$CREATE_ 
WINDOW for more in the MicroVMS Workstation Graphics Programming 
Guide information about the wd_id argument. 


dop—address 


VMS Usage; 
type: 
access: 
mechanism: 


vector_byte—unsigned 
byte—unsigned 
read only 
by reference 


DOP. The dop—address argument is the address of an array of bytes that 
comprise the DOP. This address is returned by the UISDC$ALLOCATE— 
DOP routine. 
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UISDC$QUEUE-DOP 


Description 

UISDC$QUEUE_DOP queues the specified DOP for execution in 
the specified window's request queue. The execution is performed 
asynchronously; the DOP is queued for execution, but control is immediately 
returned to the application. Unlike the UISDC$EXECUTE_DOP_ASYNCH 
routine, you cannot determine when the DOP has actually completed. 
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Appendix A 
QVSS/QDSS Data Types 


QVSS/QDSS Data Types 

This appendix illustrates and describes the data types common to the QVSS and 
QDSS systems. 

Most of these data types are 2 or 4-longword blocks that must be constructed by your 
application. However, the more complicated data type, the QVB block is predefined 
in the SYSLIBRARY:VWSSYSDEF./an definition file — where Ian is the file extension 
for the language you are using. (You choose which language definition files are 
created when you install the system.) The constants that are used in conjunction 
with the other data types in this appendix are also defined in this file. 

Some of the constants that VWSSYSDEF defines are offset values that point to each 
field in the QVB structure. You can use these predefined offsets in your application 
to access fields in the QVB. 

This appendix labels the QVB with its predefined name and each field in the 
illustrations with its predefined offset. That is, the predefined QVB name is QVB_ 
COMMON^STRUCTURE and the first field offset is QVB$L_VIDEOSIZE. 

You must "include" or "insert" the SYS$LIBRARY:VWSSYSDEF file in each module 
in which you reference it in order to use any predefined constants and offsets. You 
should become familiar with the way in which the VWSSYSDEF file defines the DOP 
structure for the programming language you are using. 
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Button Simulation Block 


buttons to be pressed mask 
buttons to be released mask 


0 


0 


Field 

buttons to be pressed mask 
buttons to be released mask 


0 

0 


Use 

Mask of the buttons to be pressed. 

Mask of the buttons to be released. 

The pointer button definitions used in the masks are 
defined by the SQVBDEF macro. They consist of the 


following symbols: 

Symbol 

Meaning 

QV$M_BUTTON_l 

Select button 

QV$M_BUTTON_2 

Button 2 

QV$M_BUTTON_3 

Button 3 

QV$M_BUTTON_4 

Button 4 


This longword must be zero. 
This longword must be zero. 
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Cursor Hot Spot 


X offset 


Y offset 


The Pointer Cursor Hot Spot data type defines the pointer cursor hot spot, which is 
that point within the 16- X 16-pixel cursor display region that is the actual cursor 
position. 


Field 

Use 

X offset 

Y offset 

The X offset from the upper left corner of the pointer 
pattern to the active point 

The Y offset from the upper left corner of the pointer 
pattern to the active point 



Data Rectangle Values Block 



MINY (bottom side value) Pixel value for bottom side of rectangle 

MAXX (right side value) Pixel value for right side of rectangle 

MAXY (top side value) Pixel value for top side of rectangle 
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Keyboard Request AST Specification Block 


AST service routine address 


AST parameter 
access mode 


0 


Field 

Use 

AST service routine address 

The address of the AST service routine is 0 if no 

AST action routine is required. If no AST routine is 
specified, input will be stored in the typeahead buffer, 
and delivered either when an AST region is declared, 
or when an Get Next Input Token QIO is issued. 

AST parameter 

The user-defined AST parameter is delivered to the 
AST action routine. It is not examined by the driver. 

access mode 

The access mode to deliver the AST is maximized with 
the current access mode. 

0 

The fourth longword must be zero. 
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Keyboard Characteristics Block 


enabled characteristics mask 


disabled characteristics mask 


keyclick volume 



enabled characteristics mask The first longword is a mask of characteristics to be 

enabled. 

disabled characteristics mask The second longword is a mask of characteristics to be 

disabled. 

The keyboard characteristics, which are defined by the 
$QVBDEF macro, consist of the following bits: 


Characteristic 

Meaning 

Q V$M _KE Y_AUTORPT 

Key held down 
automatically repeats. 
Default is on. 

QV$M_KEY_KEYCLICK 

Keyclick sounds 
on each keystroke. 
Default is on. 
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Field 


Use 


Characteristic 

Meaning 

QV$M_KEY_UDF6 

Function keys F6 
through FIO generate 
up/down transitions. 
Default is off. 

QV$M_KEY_UDF11 

Function keys Fll 
through FI4 generate 
up/down transitions. 
Default is off. 

QV$M_KEY_UDF17 

Function keys FI 7 
through F20 generate 
up/dovs^n transitions. 
Default is off. 

QV$M_KEY_UDHELPDO 

Function keys HELP 
and DO generate up 
/down transitions. 

QV$M_KEY_UDE1 

Function keys El 
through E6 generate 
up/down transitions. 
Default is off. 

QV$M_KEY_UDARROW 

Arrow keys generate 
up/down transitions. 
Default is off. 

QV$M_KEY_UDNUMKEY 

Numeric keypad keys 
generate up/down 
transitions. Default is 
off. 


keyclick volume The keyclick volume must be a value in the range of 

1 to 8; 1 is loudest and 8 is softest. If a value of 0 is 
specified, the current system default keyclick volume 
is used. 

0 The fourth longword must be 0. 
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Keystroke AST Specification Block 

AST service routine address 

AST parameter 

access mode 

input token address 


Field 

Use 

AST service routine address 

The address of the AST service routine is 0 if no 

AST action routine is required. If no AST routine is 
specified, input will be stored in the typeahead buffer, 
and delivered either when an AST region is declared, 
or when an Get Next Input Token QIO is issued. 

AST parameter 

The user-defined AST parameter is delivered to the 
AST action routine. It is not examined by the driver. 

access mode 

The access njode to deliver the AST is maximized with 
the current access mode. 

input token address 

The input token address is the address of a longword 
that receives an input token when an AST routine 
is called. Word 0 of the longword contains token 
or character data. Values in the range of 0 to 255 
map into the DIGITAL multinational character set. 
Values in the range of 256 to 512 map function keys 
into token values. Word 1 of the longword contains 
control information; bit 15 defines the status of a token 
(1 equals down, 0 equals up). By default an AST is 
only signaled on a down transition. 
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Pointer Button Characteristics Block 


enabled characteristics mask 


disabled characteristics mask 


0 


0 


Field 

enabled characteristics mask 
disabled characteristics mask 


Use 

Longword of characteristics to be enabled. 

Long word of characteristics to be disabled. 

The pointer button characteristics, which are defined 

by the $QVBDEF macro, consist of the following bit: 

Characteristic Meaning 

QV$M_BUT_UPTODOWN After a pointer button 

down transition occurs, 
the current pointer 
button request receives 
all future pointer 
button transitions until 
all pointer buttons 
return to the up 
position (regardless 
of the position of the 
pointer cursor on the 
physical screen). If this 
characteristic is disabled, 
then each up and 
down transition will be 
delivered to whichever 
button request is active 
for the current pointer 
cursor position. Default 
is on. 


0 This longword must be zero. 

0 This longword must be zero. 
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Pointer Characteristics Block 


enabled characteristics mask 


disabled characteristics mask 


0 


0 


Field Use 

enabled characteristics mask The first longword is a mask of characteristics to be 

enabled. 

disabled characteristics mask The second longword is a mask of characteristics to be 

disabled. 


The pointer characteristics, which are defined by the 
$QVBDEF macro, consist of the following bits: 


Characteristic 

Meaning 

QV$M_PTR_LEFT_HAND 

Invert buttons on mouse or 


puck. (Buttons 1 and 3 are 
switched.) 

Q V$M _PTR _IN VERT_ 

Invert buttons on stylus. 

STYLUS 

(Buttons 1 and 3 are 
switched.) 


0 

0 


Must be 0. 
Must be 0. 
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Pointer Motion AST Specification Block 


AST service routine address 
AST parameter 
access mode 

address of new pointer cursor position 

Field Use 

AST service routine address The address of the AST service routine is 0 if no AST 

action routine is required. No buffering of data in the 
typeahead buffer occurs for pointer motion ASTs. 

AST parameter The user-defined AST parameter is delivered to the 

AST action routine. It is not examined by the driver. 

access mode The access mode to deliver the AST is maximized with 

the current access mode. 

address of new pointer cursor The fourth longword contains the address of a 

position longword to receive the new pointer cursor position 

when the AST routine is called. (If the information 
is not required, this longword is 0.) The low-order 
word contains the new X pixel location of the pointer 
cursor; the high-order word contains the new Y pixel 
location of the cursor. For screen pointers, X is in the 
range 0 through 1023 with the lowest value denoting 
the left side of the screen; Y is in the range 0 through 
863 with the lowest value denoting the bottom of the 
screen. For tablet pointers, the range of X is defined in 
the Cjvb$w-.tablet—width field of the QVSS block; the 
range of Y is defined in the qvb$W—tablet—height field 
of the QVSS block. 
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New Cursor Position 


X position on physical screen 


Y position on physical screen 


Field 

Use 

X position on physical screen 

Y position on physical screen 

X position on the physical screen 

Y position on the physical screen 


New Pointer Position 


X position on physical screen 


Y position on physical screen 


Field 

Use 

X position on the physical screen 

Y position on the physical screen 

X position on the physical screen 

Y position on the physical screen 
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QVSS Block (QVB) (qvb_common. 

-Structure) 

QVB$L_VIDE0S1ZE 

QVB$L_VIDEOADDR 

QVB$L_I 

VIAPSIZE 

QVB$L_MAPADDR 

QVB$L_( 

CONTEXT 

QVB$L 

-CSR 

QVB$W_MOUS_YPIX 

QVB$W_MOUS_XPIX 

QVB$W_HEIGHT 

QVB$W_WIDTH 

QVB$W_Y_RESOL 

QVB$W_X_RESOL 

QVB$L_MOUS_XABS 

QVB$L_MOUS_YABS 

< 

1 

CD 

> 

O 

J-VIDEOSIZE 

QVB$L_MAIN 

-.VIDEOADDR 

QVB$L_MAIN_MAPSIZE 

QVB$L_MAIN_MAPADDR 

QVB$W_MAIN_MAPMAX 

QVB$W_MAIN_MAPMIN 

QVB$L-CHARACTERISTICS 

QVB$W_BUTTONS 

QVB$W_SCRSAV_TIMOUT 

QVB$W_TABLET_XPIX 

QVB$W_KEYCLICK_VOLUME 

QVB$W_TABLET_WIDTH 

QVB$W_TABLET_YPIX 

QVB$W_BUT_STATUS 

QVB$W_TABLET_HEIGHT 


(Data Structure QVSS Block (QVB) cont'd. on next page) 
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Data Structure: QVSS Block (QVB) (cont'd.) 


QVB$W_FLAGS 

DEVICE_TYPE 

BITS-PER_PIXEL 

QVB$W_SPARE_W_1 

SPARE-B-1 

CURSOR-PLANES 

QVB$W_TABLET_YSIZE 

QVB$W_TABLET_XSIZE 

QVB$F_TABLET_XRATIO 

QVB$F_TABLET_YRATIO 

QVB$L_UNIT_NUMBER 

QVB$L_POINTER_SETUP 


QVB$W_HOLD_DEFER_CNT 


The following list describes the contents of each field in the QVSS block. 

NOTE: The names contained in the following fields of the preceding data structure 

have the prefix QVB$B_The prefixes were omitted in the diagram so that the field 

names could fit within the fields. 


DEVICE^TYPE 
BITS-JPER JIXEL 
SPARE _.B._1 
CURSOR^PLANES 


Field 


Use 


QVB$L^VIDEOSIZE 

QVB$L_VIDEOADDR 

QVB$L_MAPSIZE 

QVB$L_MAPADDR 

QVB$L-CONTEXT 

QVB$L-CSR 

QVB$W-MOUS-XPIX 

QVB$W_MOUS_YPIX 

QVB$W_WIDTH 

QVB$W_HEIGHT 

QVB$W-X_RESOL 

QVB$W-Y_RESOL 


Full size of video memory, in bytes (QVSS specific). 
Address of 1st byte of video memory (QVSS specific). 
Size of scanline map, in words (QVSS specific). 
Address of scanline map (QVSS specific). 

Reserved for use by DIGITAL. 

Reserved for use by DIGITAL. 

X coordinate of the current pointer position. 

Y coordinate of the current pointer position. 
Maximum horizontal size of screen, in pixels. 
Maximum vertical size of screen, in pixels. 

Horizontal pixels per inch of physical screen. 

Vertical pixels per inch of physical screen. 
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Field 


Use 


QVB$L _MOUS_XABS 

QVB$L_MOUS_YABS 
QVB$L _MAIN_VIDEOSIZE 
QVB$L _MAIN_VIDEOADDR 
QVB$L_JV1AIN_MAPSIZE 
QVB$L _MAIN_MAPADDR 
QVB$W_MAIN_MAPMIN 
QVB$W_MAIN_MAPMAX 


QVB$L -CHARACTERISTICS 
QVB$W_SCRSAV_TIMOUT 
QVB$W_BUTTONS 
QVB$W_KEYCLICK_VOLUME 

QVB$W_TABLET_XPIX 

QVB$W_TABLEX_YPIX 

QVB$W_TABLET_WIDTH 

QVB$W_TABLET_HEIGHT 

QVB$W_BUT_STATUS 


QVB$B_BITS_PER_PIXEL 

QVB$B_DEVICE_TYPE 


Pointer X position on signed 32-bit virtual coordinate 
space. Used to obtain relative motion when cursor 
hardware tracking not used. 

Pointer Y position on signed 32-bit virtual coordinate 
space. 

Size of video memory allocated to the windowing 
system, in bytes (QVSS specific). 

Address of video memory allocated to the windowing 
system (QVSS specific). 

Size of the windowing system scanline map (QVSS 
specific). 

Address of the windowing system scanline map 
(QVSS specific) 

Entry number of the lowest entry in the scanline map 
last updated (QVSS specific). 

Entry number of the highest entry in the scanline map 
last updated (QVSS specific). (Updating these fields 
permits the driver to update only the modified portion 
of the scanline map, using the main windowing 
system scanline map area.) 

Current systemwide windowing characteristics. 

Current screen saver timeout value, in seconds. 

This field no longer supported. 

Default keyclick volume. Value must be in the range 
of 1 to 8 (1 is loudest). Default is 3. 

The current X position on a tablet, in pixels. 

The current Y position on a tablet, in pixels. 

Maximum horizontal size of a tablet, in pixels. 
Maximum vertical size of a tablet, in pixels. 

Current up/down status of the pointing device 
buttons. If a bit is set, the button is down. The bit 
positions correspond to the button numbers. That is, 
the select button, (number 1) is represented by the first 
bit, and so on. 

Number of bits per pixel. Black and white systems 
have a value of 1. Color systems may be 4 or 8. 

Value identif)dng driver. A value of 0 indicates QVSS, 
a 1 indicates QDSS. 
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Field 

Use 

QVB$W_FLAGS 

Internal flags. The following fields are defined within 
qvb$W-^flags: 


Field 

Use 

QVB$V_TABLET 

This field is one bit long, 
and starts at bit 18. 

Indicates that tablet is 
present; 0 equals pointer is 
present. 

QVB$V_STYLUS 

This field is one bit long, 
and starts at bit 19. It 
indicates that tablet stylus 
is present. 


QVB$B_CURSOR_PLANES 

QVB$B_SPARE_B_1 

QVB$W_SPARE_W_1 

QVB$W_TABLET_XSIZE 

QVB$W_TABLET_YSIZE 

QVB$E_TABLET_XRATIO 

QVB$F_TABLET_YRATIO 

QVB$L_UNIT_NUMBER 

QVB$L_POINTER_SETUP 


The number of planes in the hardware cursor. A color 
cursor has two planes. 

Reserved to DIGITAL. 

Reserved to DIGITAL. 

Width of tablet, in centimeters. This is an integer 
value. 

Height of tablet, in centimeters. This is an integer 
value. 

Floating-point ratio of screen width to tablet width, in 
pixels. 

Floating-point ratio of screen height to tablet height, 
in pixels. 

Number of the video device unit associated with the 
QVB. 

System characteristics. Contains the current status for 
system wide pointer characteristics. The following 
fields are defined within qvb$l—pointer__setup. 


Field 

Use 

QV$V_PTR_LEFr_ 

Indicates pointer is left 

HAND 

handed if bit is set 

QV$V_PTR_INVERT_ 

Indicates tip of stylus is 

STYLUS 

select button if bit is set 


QVB$W_HOLD_DEFER_CNT Reserved for use by DIGITAL. 


Constants - The following constants are defined in conjunction with the QDB$. 
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Constant 

Value 

BCEY$C_SELECT 

The select button. 

KEY$C_BUTTON_l 

Pointer device button 1. 

KEY$C_BUTTON_2 

Pointer device button 2. 

KEY$C_BUTTON_3 

Pointer device button 3. 

KEY$C_F1 

Function key FI. 

KEY$C_F2 

Function key F2. 

KEY$C_F3 

Function key F3. 

KEY$C_F4 

Function key F4. 

KEY$C_F5 

Function key F5. 

QVB$C_QVSS 

QVSS driver type constant (= 0) 

QVB$C_QDSS 

QDSS driver type constant (= 1) 

QVB$C_LENGTH 

The length of the QVB structure. 





QVSS/QDSS Data Types A-17 


Reserved Function Keystroke AST Specification Block 


AST service routine address 


AST parameter 


access mode 


input token address 


Field 

Use 

AST service routine address 

The address of the AST service routine is 0 if no AST 
action routine is required. 

AST parameter 

The user-defined AST parameter is delivered to the 
AST action routine. It is not examined by the driver. 

access mode 

The access mode to deliver the AST is maximized with 
the current access mode. 

input token address 

The input token address is the address of a longword 
that receives an input token when an AST routine is 
called. Word 0 of the longword contains token data 
defined by the $SMGDEF macro for these function 
keys. By default an AST is only signaled on a down 
transition. 
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Screen Rectangle Values Block 



Use 

Pixel value for left side of rectangle 
Pixel value for bottom side of rectangle 
Pixel value for right side of rectangle 
Pixel value for top side of rectangle 


Field 

MINX (left side value) 
MINY (bottom side value) 
MAXX (right side value) 
MAXY (top side value) 
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System Characteristics Block 


enabled characteristics mask 


disabled characteristics mask 


keyclick volume 


screen saver timeout value 


Field Use 

enabled characteristics mask The first longword is a mask of characteristics to be 

enabled. 

disabled characteristics mask The second longword is a mask of characteristics to be 

disabled. 

The system characteristics, which are defined by the 
$QVBDEF macro, consist of the following bits: 


Characteristic 

Meaning 

QV$M_KEY_AUTORPT 

Key held down automati¬ 
cally repeats. 

QV$M_KEY_KEYCLICK 

Keyclick sounds on each 
keystroke. Default is on. 

QV$M_KEY_UDF6 

Function keys F6 through 
FIO generate up/down 
transitions. Default is off. 

QV$M_KEY_UDF11 

Function keys Fll through 
FI4 generate up/down 
transitions. Default is off. 

QV$M_KEY_UDF17 

Function keys FI 7 through 
F20 generate up/down 
transitions. Default is off. 

QV$M_KEY_UDHELPDO 

Function keys HELP and 

DO generate up/down 
transitions. 
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Field 

Use 



QV$M_KEY_UDE1 

Function keys El through 

E6 generate up/down 
transitions. Default is off. 


QV$M_KEY_UDARROW 

Arrow keys generate up 
/down transitions. Default 
is off. 


QV$M_KEY_UDNUMKEY 

Numeric keypad keys 
generate up/down 
transitions. Default is 
off. 


QV$M_SYS_SCRSAV 

Disable video output to 
monitor if no input activity 
occurs within the number 
of minutes specified in 
the fourth longword. Any 
keystroke, pointer button 
transition, or pointer motion 
will reset the timer and 
reactivate a disabled screen. 
The default is on. 

keyclick volume 

The keyclick volume must be 
8; 1 is loudest and 8 is softest. 

a value in the range of 1 to 
Default is 3. 

screen saver timeout value 

The screen saver timeout value represents the number of 
minutes of inactivity that must elapse before the screen 
saver is activated. The value must be in the range of 1 to 
1440. If a value of 0 is specified, then the timeout value is 
not changed. Default is 15. 
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QDSS-Specific Data Types 

This appendix illustrates and describes the data types of the QDSS system. 

These data types are predefined in the SYSLIBRARY:VWSSYSDEF./an definition file 
— where Ian is the file extension for the language you are using. (You choose which 
language definition files are created when you install the system.) 

VWSSYSDEF defines data type structures and constants, including offset values 
that define each field in the structure. You can use these predefined offsets in your 
application to access fields. 

This appendix labels each data type with its predefined name and each field in the 
illustrations with its predefined offset. 

For example, VWSSYSDEF defines a structure DOP__STRUCTURE in which it defines 
an offset DOP$W-_ITEM_TYPE. Once you associate the storage with a structure, you 
can use the offset to reference into the structure. 

You must "include" or "insert" the SYS$LIBRARY:VWSSYSDEF file in each module 
in which you reference it in order to use any predefined constants and offsets. You 
should become familiar with the way in which the VWSSYSDEF file defines the DOP 
structure for the programming language you are using. 
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DOP Queue Structure (req_structure) 


REQ$L -REQU EST_FLI N K 


REQ$L_REQUEST_BLINK 


REQ$I_RETURN_FLINK 


REQ$L_RETURN_BLINK 


REQ$L _RETU RN_LARGE_FLI N K 


REQ$L_RETURN_LARGE_BLINK 


REQ$W_LARGE_DOP_SIZE 


REQ$W_SMALL_DOP_SIZE 


REQ$I_APPLICATION-RESERVED 


The following list describes the contents of each field in the request queue definition. 


Field 


Use 


REQ$L _REQUEST_FLINK 
REQ$L _REQUEST_BLINK 
REQ$L _RETURN_FLINK 
REQ$L -RETURN-BLINK 
REQ$L-RETURN-LARGE-FLINK 
REQ$L -RETURN -LARGE -BLINK 
REQ$ W-L ARGE -DOP-SIZE 

REQ$ W-SM ALL -DOP-SIZE 

REQ$L-APPLICATION-RESERVED 


Pending drawing operation queue header 
Previous drawing operation queue header 
Forward link for the ordinary return queue 
Backward link for the ordinary return queue 
Forward link for the large DOP return queue 
Backward link for the large DOP return queue 

Size of a DOP returned to the large DOP return 
queue 

Size of a DOP returned to the ordinary return 
queue 

A longword reserved for use by the application 
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( 

Constants - The following constants are defined in conjunction with the REQ$. 


Constant 

Value 

REQ$K_RETURN_OFFSET 

REQ$K_LENGTH 

Offset from beginning of structure to return queue 
Length of the structure 



QDSS Block (QDB) (qvb_qdss—structure) 


; QVBDEF$$_QD_COMMQN_FILL (120 bytes) ^ 

QDB$L_SYSVP 

QDB$W_ON_SCREEN_Y 

QDB$W_ON_SCREEN_X 

QDB$W_ON_SCREEN_HEIGHT 

QDB$W_ON_SCREEN_WIDTH 

QDB$W_SCROLL_Y 

QDB$W_SCROLI_X 

QDB$W_SCROLI_HEIGHT 

QDB$W_SCROLL-WIDTH 

QDB$W_FREE_1_Y 

QDB$W_FREE_1_X 

QDB$W_FREE_1_HEIGHT 

QDB$W_FREE_1_WIDTH 

QDB$W_FREE_2_Y 

QDB$W_FREE_2_X 

QDB$W_FREE_2_HEIGHT 

QDB$W_FREE_2_WIDTH 

QDB$W_FREE_3_Y 

QDB$W_FREE_3_X 

QDB$W_FREE_3_HEIGHT 

QDB$W_FREE_3_WIDTH 

QDB$W_FONT_Y 

QDB$W_FQNT_X 

QDB$W_FONT_HEIGHT 

QDB$W_FQNT_WIDTH 


(Data Structure QDSS Block (QDB) cont’d. on next page) 
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Data Structure: QDSS Block (QDB) (cont’d.) 

QDB$W_CLIP_SAVE_Y QDB$W_CLIP_SAVE_X 

QDB$W_CLIP_SAVE_HEIGHT QDB$W_CLIP_SAVE_WIDTH 

QDB$L-COLOR-INDICES 
ODB$L -COLOR-COLORS 
ODB$L-COLOR-RBITS 
ODB$L-COLOR-GBITS 
ODB$L -COLOR-BBITS 
ODB$L-COLOR-IBITS 
ODB$L-COLOR-RES-INDICES 
ODB$L-COLOR-REGEN 
ODB$L -COLOR-MAPS 
ODB$l_COLOR-INTENSITY-FLAG 

The following list describes the contents of each field in the QDSS block. Note that 
the first part of the QDB is actually the QVB. See Appendix A for a full explanation 
of the QVB fields. 
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Field 


Use 


Q VBDEF$_QD_COMMON _FILL 

QDB$L_SYSVP 

QDB$W_ON-SCREEN_X 

QDB$ W_ON -SCREEN _X 

QDB$ W_ON -SCREEN -WIDTH 

QDB$W-ON-SCREEN-HEIGHT 

QDB$W-SCROLL_X 

QDB$W-SCROLL-Y 

QDB$ W-SCROLL -WIDTH 
QDB$ W-SCROLL -HEIGHT 
QDB$W-FREE-1-X 

QDB$W-FREE-1-Y 

QDB$W-FREE-1-WIDTH 

QDB$W-FREE-1-HEIGHT 

QDB$W-FONT-X 

QDB$W-FONT-Y 

QDB$W-FONT-WIDTH 
QDB$W-FONT_HEIGHT 
QDB$L -COLOR-INDICES 
QDB$L -COLOR-COLORS 
QDB$L -COLOR-RBITS 
QDB$L -COLOR-GBITS 
QDB$L -COLOR-BBITS 
QDB$L-COLOR-IBITS 
QDB$L -COLOR-RES-INDICES 
QDB$L-COLOR-REGEN 

QDB$L -COLOR-MAPS 


The part of the block occupied by the QVB common 
block 

Systemwide viewport ID 

X coordinate of the lower left-hand corner of onscreen 
memory 

Y coordinate of the lower left-hand corner of onscreen 
memory 

Width of onscreen memory 
Height of onscreen memory 

X coordinate of the lower left-hand corner of the scroll 
area 

Y coordinate of the lower left-hand corner of the scroll 
area 

Width of the scroll area 
Height of the scroll area 

X coordinate of the lower left-hand corner of writeable 
memory 

Y coordinate of the lower left-hand corner of writeable 
memory 

Width of writeable memory 
Height of writeable memory 

X coordinate of the lower left-hand corner of bitmap 
storage area 

X coordinate of the lower left-hand corner of bitmap 
storage area 

Width of the bitmap storage area 
Height of the bitmap storage area 
Color map size 

Maximum number of possible colors 

Number of bits of precision for red 

Number of bits of precision for green 

Number of bits of precision for blue 

Number of bits of intensity precision 

Number of color map entries reserved by the system 

Color regeneration characteristics; on a QDSS system 
color regeneration is retroactive 

Always 1 for QDSS 
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Field Use 

QDB$L_COLOR_INTENSITY_ Indicates whether color or intensity mode; 1 = system 

FLAG setup for intensity values; 0 = RGB expected 

Constants - The following constants are defined in conjunction with the QDB. 
Constant Value 

QVB$C_LENGTH The length of the QVB structure. 



R ET$I_R ETU R N_FLI N K 

RET$L_RETURN_BLINK 


RET$L_RETURN_LARGE_FLINK 

RET$L_RETURN_LARGE_BLINK 

RET$W_LARGE_DOP_SIZE RET$W_SMALL_DOP_SIZE 

RET$I_APPLICATION-RESERVED 
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The following list describes the contents of each field in the request queue definition. 


Field 


Use 


RET$L_RETURN_FLINK 

RET$L_RETURN_BLINK 

RET$L _RETURN_LARGE_FLINK 

RET$L_RETURN_LARGE_BLINK 

RET$W_LARGE_DOP_SIZE 

RETS W_5M ALL _DOP_SIZE 

RETSL _APPLIC ATION -RESERVED 


Forward link for the ordinary return queue 
Backward link for the ordinary return queue 
Forward link for the large DOP return queue 
Backward link for the large DOP return queue 

Size of a DOP returned to the large DOP return 
queue 

Size of a DOP returned to the ordinary return 
queue 

A longword reserved for use by the application 


Transfer Parameter Block (TPB) (tpb—Structure) 


TPB$W_X_SOURCE 

TPB$B_SIZE TPB$B_TYPE 

TPB$W_WIDTH 

TPB$W_Y_SOURCE 

TPB$W_X_TARGET 

TPB$W_HEIGHT 

TPB$W_X_TARGET_VEC1 

TPB$W_Y_TARGET 

TPB$W_L _TARGET_VEC1 

TPB$W_Y_TARGET_VEC1 

TPB$W_Y_TARGET_VEC2 

TPB$W_X_TARG ET_VEC2 


TPB$W_L _TARGET_VEC2 
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The following list describes the contents of each field in the transfer parameter block. 


Field 

Use 

TPB$B_TYPE 

Type of transfer being performed, either bitmap-to-processor 
(BTP), processor-to-bitmap (PTB), or bitmap-to-bitmap Use 
the constants defined below to load this field. 

TPB$B_SIZE 

Reserved to DIGITAL. 

TPB$W_X_SOURCE 

X coordinate of lower left-hand corner of source bitmap. 

TPB$W_Y_50URCE 

Y coordinate of lower left-hand corner of source bitmap. 

TPB$W_WIDTH 

Width of source bitmap. 

TPB$W_HEIGHT 

Height of source bitmap. 

TPB$W_X_TARGET 

X coordinate of lower left-hand corner of target bitmap. (Only 
specified for bitmap-to-bitmap transfer.) 

TPB$W_Y_TARGET 

Y coordinate of lower left-hand corner of target bitmap. 

TPB$ W_X _TARGET_VEC 1 

Reserved to DIGITAL. 

TPB$ W_Y_TARGET_VEC 1 

Reserved to DIGITAL. 

TPB$W_L_TARGET_VEC1 

Reserved to DIGITAL. 

TPB$W_X_TARGET_VEC2 

Reserved to DIGITAL. 

TPB$W_Y_TARGET_VEC2 

Reserved to DIGITAL. 

TPB$W_L _TARGET_VEC2 

Reserved to DIGITAL. 
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Constants - The following constants are defined in conjunction with the TPB. 


Constant 

Value 

TPB$C_BITMAP_XFR 

TPB$C_SOURCE_ONLY 

TPB$C_SOURCE -LENGTH 

TPB$C_BITMAP_XFR_LENGTH 

TPB$C_LENGTH 

Used to specify a bitmap-to-bitmap transfer. 

Used to specify a BTP or PTB transfer. 

Structure length for BTP or PTB transfers 

Structure length for a bitmap-to-bitmap transfer. 

Full structure length. 


Update Region Definition Block (urd—structure) 


URD$W_Y_MIN 

URD$W_X_MIN 

URD$W_Y_MAX 

URD$W_X_MAX 

URD$W_Y_BASE 

URD$W_X_BASE 
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The following list describes the contents of each field in the update region definition 
block. 


Field 

Use 

URD$W_X_MIN 

Viewport-relative X coordinate of the lower left-hand 
corner of defined region 

URD$W_Y_MIN 

Viewport-relative Y coordinate of the lower left-hand 
corner of defined region 

URD$W_X_MAX 

Viewport-relative X coordinate of the upper right-hand 
corner of defined region 

URD$W_Y_MAX 

Viewport-relative Y coordinate of the upper right-hand 
corner of defined region 

URD$W_X_BASE 

Absolute X coordinate from lower left-hand corner of 
defined region 

URD$W_Y_BASE 

Absolute X coordinate from lower left-hand corner of 
defined region 

Constants - The following constants are defined in conjunction with the URD. 

Constant 

Value 

URD$C_LENGTH 

Length of the structure. 








Appendix C 
QDSS Writing Modes 


This appendix contains a table of all the QDSS writing modes. They describe the 
logical operations that may be performed when two graphic objects intersect. This 
operation occurs between the destination, the bits making up the existing bitmap 
pixel, and the source index, a value selected by the application in the DOP structure. 
The results of this operation are tested against the foreground and background color 
to determine the bit settings for the pixels making up the intersecting area. 

These writing mode names are acronyms that reflect the function being performed 
by the mode. The names can be interpreted (and remembered) by reading D for 
destination, S for source index, N for NEGATE, A for AND, O for OR, and X for 
XOR — with all expressions written in reverse Polish notation. 
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Table C-1 QDSS Writing Modes 


QDSS Writing Modes 

Function 

WRIT$C_ZEROES 

All resulting bits are set to 0. 

WRlT$C_DSON 

The destination is ORed with source index, then the result is 
negated. 

WRIT$C_DNSA 

The destination is negated, then ANDed with the source 
index. 

WRIT$C_DN 

The destination is negated. 

WRIT$C_DSNA 

The source index is negated, then ANDed with the 
destination. 

WRIT$C_SN 

The source index is negated. 

WRIT$C_DSX 

The destination is XORed with the source index. 

WRIT$C_DSAN 

The destination is ANDed with the source index, then the 
result is negated. 

WRIT$C_DSA 

The destination is ANDed with the source index. 

WRIT$C_DSXN 

The destination is XORed with the source index, then the 
result is negated. 

WRIT$C_S 

The result is equal to the source index. 

WRIT$C_DNSO 

The destination is negated, then ANDed with the source 
index. 

WR1T$C_D 

The result is equal to the destination. 

WRIT$C_DSNO 

The source index is negated, then ORed with the destination. 

WRIT$C_DSO 

The destination is ORed with the source index. 

WRIT$C_ONES 

All resulting bits are set to 1. 
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In addition, you may specify the following modifiers with the writing modes (by 
ANDing the two values). 


Table C-2 QDSS Writing Mode Modifiers 


Modifier 

Function 

WRIT$M -USE -MASK _2 

Specifies that the mask specified in the bitmap ID field of the 
DOP be used to determine whether the resulting pixel should 
be written. 

WRIT$M -COMP-MASK -2 

Specifies that the complement of the mask specified in the 
bitmap ID field of the DOP be used to determine whether the 
resulting pixel should be written. 

WR1T$M _NO-SRC-COMP 

Specifies that the complement of the source index should not 
be used in the logical operation. 
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QVSS Programming Example 


D.1 Programming 

This appendix contains a sample application program for the QVSS driver. 

D.1.1 Program Functions 

The test program in Section 2.1.2 is an example of how a typical program might be 
designed for the QVSS driver. This simple program, using most of the QIO functions 
available to the QVSS driver, performs the following operations: 

1. Sets system windowing characteristics. 

a. Enables autorepeat and keyclick; disables keys F6 to FIO and the arrow keys 
from generating up-transition ASTs. 

b. Sounds the bell to indicate that the characteristics have been set. 

2. Sets up permanent cursor pattern. 

a. Sets up a new default system cursor pattern. 

3. Sets cursor regions — Sets up two separate cursor regions on the screen. One 
region will be located in the lower left comer and have a block-shaped cursor. 
The other region will be in the upper right corner and will have a cross-shaped 
cursor. 

4. Sets up two one-shot requests on keyboard channel 1. 

5. Sets up keyboard region 1 to be a French keyboard. 

6. Sets up a private two-stroke compose table for keyboard region 1. 

7. Sets up a private three-stroke compose table for keyboard region 1. 

8. Sets keyboard regions. 

a. Sets up two keyboard regions. Each region specifies a keyboard AST and a 
control AST. 
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b. The keyboard AST specified for each region performs the following actions: 
— Sends an acknowledgment message to the terminal. 

— Sends (echoes) the character typed to the terminal. 

— If the character was a "C", issues a cycle QIO on the keyboard list. 

— The cycle QIO causes the other keyboard region to become active. 

— A control AST for the new region is then delivered. 

— If the character "F" was typed, sets event flag 2, which in turn terminates 
the program. 

c. The control AST specified for each region sends a message to the terminal 
indicating that a control AST was delivered. 

9. Enables AST region for pointer buttons. 

a. Sets up an AST to be called each time a pointer button is depressed/released 
in the specified region. 

b. The AST routine determines which button was changed and prints a message 
identifying the pointer button. The AST routine then determines whether 
the button is currently up or down and prints a message to that effect. 

10. Enables AST for function key F5 — Sets up an AST to be called each time 
function key F5 is pressed. 

— The F5 AST routine will issue a cycle QIO on the keyboard list. 

— The cycle QIO causes the control AST for the new keyboard region to be 
delivered. 

11. Enables an AST region for pointer motion. 

a. Sets up an AST to be called each time the pointer moves within a specified 
region. 

b. The AST routine will print a message indicating that the pointer has moved. 

12. Simulates keyboard input on keyboard channel 2 — Simulates the input of a 
character string on keyboard region 2. 

13. Waits for event flag 2 to be set. 

14. Exits program when event flag 2 is set. 
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D.1.2 QVSS Program Example 


.TITLE QVSS PORT DRIVER TEST PROGRAM 
.IDENT /02/ 

QVSS PORT DRIVER TEST PROGRAM 

.SBTTL DECLARATIONS 
Define symbols 

IIODEF ; Define I/O function codes 

$QVBDEF ; QVSS definitions 


Allocate workstation descriptor and channel number storage 


WS.DEVNAM: 

.ASCID /SYSIWORKSTATION/ 

SYS.CHANl: 

.BLKW 1 ; 

CUR.CHANl: 

.BLKW 1 ; 

CUR.CHAN2: 

.BLKW 1 ; 

KBD.CHANl: 

.BLKW 1 ; 

KBD.CHAN2: 

.BLKW 1 ; 

BUT.CHAN: 

.BLKW 1 : 

MOUSE.CHAN: 

.BLKW 1 ; 

FNKEY_F6_CHAN: 

.BLKW 1 ; 


; Logical name of workstation 
Channel number storage 
Channel number storage 
Channel number storage 
Channel number storage 
Channel number storage 
Channel number storage 
Channel number storage 
Channel number storage 


BUTTON: 

.BLKL 1 
MOUSE.XY: 

.BLKL 1 


State of buttons 

Current pointer X,Y coordinates 


CHARACTER: 

.BLKL 1 
DESC: .LONG 2 

.LONG CHARACTER 


Keyboard character 


lOSB.BLOCK: 

.QUAD 
DESCl: .LONG 
.LONG 


0 

1 

I0SB_BL0CK+4 


; lOSB descriptor 
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.SBTTL START - MAIN ROUTINE 

+ + 

FUNCTIONAL DESCRIPTION: 

START PROGRAM 


INPUT PARAMETERS: 
NONE 

OUTPUT PARAMETERS: 
NONE 


START: 

.WORD 

$ASSIGN_S DEVNAM=WS_DEVNAM,- 
CHAN=SYS_CHAN1 
BLBS R0.5$ 

BRW ERROR 

6$: BSBW SET.CHARACTERISTICS 

BSBW SET_PERM_CURSOR 

BSBW SET.CURSOR 

BSBW SET.ONESHOT 

BSBW SET.FRENCH.KB 

BSBW SET_C0MP0SE2_TABLE 

BSBW SET.COMPOSES.TABLE 

BSBW SET.KBDAST 

BSBW SET.BUTTONAST 

BSBW SET_FNKEYAST 

BSBW SET.MOUSEAST 

BSBW SIMULATE.INPUT 
ICLREF.S EFN=#2 

$WAITFR_S EFN=#2 


Entry mask 
Assign channel using 
logical name and channel number 
Check for success 
Report error on failure 

Set up system characteristics 

Set up new system wide cursor pattern 

Set up cursors 

Set up one-shot on keyboard channel 1 

Set up French keyboard on keyboard 1 

Set up 2-stroke compose table on kbd 1 

Set up 3-stroke compose table on kbd 1 

Set keyboard AST 

Set up button region AST 

Set up function key AST 

Set up pointer region AST 

Simulate input on keyboard 2 

Clear event flag #2 

Wait for event flag #2 


ERROR: $EXIT.S RO 
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.SBTTL SET.CHARACTERISTICS - SET SYSTEM WINDOWING CHARACTERISTICS 

+ + 

FUNCTIONAL DESCRIPTION: 


Set a couple of SYSTEM windowing characteristics and sound the 
bell after they are set, 

INPUT PARAMETERS: 

NONE 


OUTPUT PARAMETERS: 
NONE 


SET^CHARACTERISTICS: 

MOVL #IO$C_QV_MODIFYSYS.RO 
$QI0W_S CHAN=SYS_CHAN1.- 

FUNC=#I0$_SETM0DE,- 
P1 = (RO),- 
P4 = #CHAR_BLOCK 
BLBS R0.10$ 

BRW ERROR 

10$: MOVL #IO$C.QV_SOUND,RO 

$QIOW_S CHAN=SYS_CHAN1,- 

FUNC=#IO$.SETMODE,“ 

PI = (RO).- 
P2 = #QV$M_SOUND_BELL 
BLBS R0.20$ 

BRW ERROR 

20$: RSB 


Modify characteristics code 
Use system channel 
QIO function code 
QVSS function code 
Characteristics block 
Check for success 


Sound code 


Bell sound modifier 
Check for success 
Report error on failure 


CHAR.BLOCK: 

.LONG 

.LONG 

.LONG 

.LONG 


<QV$M_SYS_AUTORPT!QV$M_SYS_KEYCLICK> 
<QV$M_SYS_UDF6!QV$M_SYS_UDARROW> 

5 

30 


Characteristics block 

Enable these 


Disable these 
Keyclick volume 
Screen saver timeout 
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.SBTTL SET_PERM_CURSOR - SET UP NEW SYSTEM CURSOR 

;++ 

; FUNCTIONAL DESCRIPTION: 


Set a new system wide cursor pattern. 

INPUT PARAMETERS: 

NONE 

OUTPUT PARAMETERS: 

NONE 


SET_PERM_CURSOR: 


MOVL 

#<IO$C«QV.SETCURSOR - ; 

Define system cursor 


!IO$M_QV_LOAD_DEFAULT>,RO 

; Default modifier 

iqiow.s 

CHAN^SYS.CHANl,- 
FUNC*#IO$_SETMODE.- 
P1 =(R0),- 



P2=#M0USE$BM,- ; 

Cursor description 


P4»«M0USE$H0TSP0T ; 

Cursor hot spot 

BLBS 

R0,10$ ; 

Check for success 

BRW 

10$: RSB 

ERROR ; 

Report error on failure 

MOUSE$BM: 


Bitmap definition of 

.WORD 

^bOOOOOOl110000000 ; 

pointer cursor used in call 

.WORD 

-bOOOOOllOOOOOOOOO 


.WORD 

-bOOOOOOllOOOOOOOO 


.WORD 

^bOOOOOOOl10000000 


.WORD 

'‘bOOllllllllllllOO 


.WORD 

'‘bOlOOOOOOOOOOOOlO 


.WORD 

‘‘bllOllOOllOOllOll 


.WORD 

^bllOllOOllOOllOll 


.WORD 

“bllOllOOllOOllOll 


.WORD 

-‘bllOOOOOOOOOOOOll 


.WORD 

^bllOOOOOOOOOOOOll 


.WORD 

"bllllOOOOOOOOllll 


.WORD 

^bllOOllOOOOllOOll 


.WORD 

"bOllOOOllllOOOllO 


.WORD 

^bOOllOlOOOOlOllOO 


.WORD 

^bOOOllllllllllOOO 


MOUSEIHOTSPOT: 

; 

Pointer hot spot definition 

.LONG 

9 


.LONG 

0 



; The following two cursor patterns (although not used by the appliation) 
; are provided to show alternative patterns 
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PENCIL: .WORD 

^XOOOO 

.WORD 

^XOOOO 

.WORD 

^X0700 

.WORD 

^X0880 

.WORD 

“X0880 

.WORD 

^X1700 

.WORD 

"XllOO 

.WORD 

-X2200 

.WORD 

'‘X2200 

.WORD 

-X4400 

.WORD 

-X4400 

.WORD 

“Xc800 

.WORD 

^XfOOO 

.WORD 

“XeOOO 

.WORD 

“XcOOO 

.WORD 

-X8000 

PENCIL_HS: 

.LONG 

0 

.LONG 

15 

SPRAYCAN: 

.WORD 

“X8000 

.WORD 

•X2000 

.WORD 

“X8b00 

.WORD 

“X2780 

.WORD 

^X8680 

.WORD 

“XOfcO 

.WORD 

-X0840 

.WORD 

^X09c0 

.WORD 

"X0940 

.WORD 

“XOOcO 

.WORD 

^X0940 

.WORD 

^X09c0 

.WORD 

“XOQcO 

.WORD 

-X0840 

.WORD 

^X0840 

.WORD 

^XOfcO 


SPRAYCAN_HS: 

.LONG 0 
.LONG 1 


; Pencil cursor definition 


; Pencil hot spot definition 


; Spraycan cursor definition 


: Spraycan hot spot definition 
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.SBTTL SET.CUKSOR - SET UP CURSOR REGIONS 


FUNCTIONAL DESCRIPTION: 

Set two cursor regions for the screen. 

INPUT PARAMETERS: 

NONE 

OUTPUT PARAMETERS: 

NONE 


SET.CURSOR: 


$ASSIGN_S DEVNAM=WS_DEVNAM.- 

; Assign one cursor channel using 


CHAN=CUR.CHAN1 

; logical name and channel number 

BLBS 

R0.10$ 

; Check for success 

BRW 

ERROR 


10$: $ASSIGN_S DEVNAM=WS_DEVNAM,- 

; Assign another cursor channel using 


CHAN=CUR_CHAN2 

: logical neune sjid channel number 

BLBS 

R0,20$ 


BRW 

ERROR 


20$: MOVL 

#IO$C_QV_SETCURSOR.RO 

; Define cursor region code 

$QIOW_S CHAN=CDR_CHAN1.- 

; On cursor channel 1 


FUNC=#IO$.SETMODE.- 



PI =(R0),- 



P2=#QV$CURS0R1.- 

; Cursor description 


P6=#REGI0N1 

; Cursor region 1 definition 

BLBS 

R0.30$ 

; Check for success 

BRW 

ERROR 


30$: MOVL 

#IO$C^QV.SETCURSOR.RO 

; Define cursor region code 

$QIOW_S 

CHAN=CUR_CHAN2.“ 

; On cursor cheoinel 2 


FUNC=#IO$_SETMODE.- 



P1=(R0).- 



P2=#QV$CURS0R2.“ 

; Cursor description 


P6=#REGI0N2 

; Cursor region 2 definition 

BLBS 

R0.40$ 

; Check for success 

BRW 

ERROR 


40$: RSB 



REGIONl: 


; Cursor region 1 definition 

.LONG 

20 

; Lower left corner (ADC) 

.LONG 

20 


.LONG 

300 

; Upper right corner (ADC) 

.LONG 

300 


REGI0N2: 


; Cursor region 2 definition 

.LONG 

400 

; Lower left corner (ADC) 

.LONG 

400 


.LONG 

800 

; Upper right corner (ADC) 

.LONG 

800 
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QV$CURS0R1: 

.WORD 

.WORD 

.WORD -bllllllllllllllll 
.WORD -bllllllllllllllll 
.WORD "bllllllllllllllll 
.WORD ^bllllllllllllllll 
.WORD -bllllllllllllllll 
.WORD -bllllllllllllllll 
.WORD -bllllllllllllllll 
.WORD ^bllllllllllllllll 
.WORD 

.WORD -bllllllllllllllll 
.WORD -bllllllllllllllll 
.WORD “bllllllllllllllll 
.WORD '‘bllllllllllllllll 
.WORD -bllllllllllllllll 

QV$CURS0R2: 

.WORD ^bOOOOOl1110000000 
.WORD ^bOOOOOl1110000000 
.WORD “bOOOOOl1110000000 
. WORD ''bOOOOOl 1110000000 
.WORD “bOOOOOl1110000000 
.WORD “bOOOOOl1110000000 
.WORD ^bOOOOOl1110000000 
.WORD ^bllllllllllllllll 
.WORD ^bllllllllllllllll 
.WORD ^bOOOOOl1110000000 
.WORD “bOOOOOl1110000000 
.WORD -bOOOOOl1110000000 
.WORD “bOOOOOl1110000000 
.WORD “bOOOOOl1110000000 
.WORD ^bOOOOOl1110000000 
.WORD -bOOOOOl1110000000 

.SBTTL SET.ONESHOT - SET UP 


FUNCTIONAL DESCRIPTION: 


; 16 * 16 Cursor pattern 1 (solid) 


; 16 * 16 Cursor pattern 2 (cross) 


ONE-SHOT QIO 


Set up two 'one-shot* keyboard character reads 
on keyboard channel 1 by enabling a keyboard region 
w/o an AST. The input goes to the typeahead buffer, 
and the one-shots read it one character at a time. 


INPUT PARAMETERS: 
NONE 

OUTPUT PARAMETERS: 
NONE 


SET.ONESHOT: 

$ASSIGN_S DEVNAM=WS_DEVNAM.- 
CHAN=KBD_CHAN1 
BLBS R0.10$ 

BRW ERROR 


Assign a keyboard channel using 
logical name and cheumel number 
Check for success 
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10 $: 


20 $: 


30$: 


MOVL «IO$C.QV.ENAKB.RO 
$QI0W_S CHAN=KBD_CHAN1.- 

FUNC=#I0$_SETM0DE,- 
P1=(R0).- 
P2*#P2„BL0CK 
BLBS R0,20$ 

BRW ERROR 

IQIO.S CHAN«KBD.CHAN1.- 

FUNC=#IO$_READVBLK,- 
lOSB = lOSB^BLOCK,- 
ASTADR = ONE.SHOT_AST.- 
ASTPRM = #ONESHOT_ACK,- 
P2 * #IO$C^QV.ENAKB 
BLBS R0.30$ 

BRW ERROR 

$QIO_S CHAN=KBD.CHAN1.- 

FUNC=#IO$_READVBLK.- 
lOSB * lOSB.BLOCK,- 
ASTADR = ONE_SHOT.AST.- 
ASTPRM = #ONESHOT_ACK,- 
P2 = #IO$C_QV.ENAKB 
RSB 


Enable keyboard region code 
On keyboard channel 1 


AST specification block 
Check for success 

Queue 2 one-shot reads 
QIO Read code 
lOSB block 

AST that reads character 
Acknowledgment message 
Indicates keyboard list 
Check for success 


P2.BL0CK: 

.LONG 0 
.LONG 0 
.LONG 0 
.LONG 0 


AST specification block 1 
AST address 
AST parameter 
AST delivery mode 
Input token 


ONESHOT.ACK: ; Acknowledgment message 

.ASCID /ONE SHOT RECEIVED ON CHANNEL 1/ 





QVSS Programming Example 

Programming 


.SBTTL SET_FRENCH_KB - SET UP A FRENCH KEYBOARD 

++ 

FUNCTIONAL DESCRIPTION: 

Set up a French keyboard on keyboard channel 1. 

INPUT PARAMETERS: 

NONE 

OUTPUT PARAMETERS: 

NONE 


SET.FRENCH.KB: 

; Request that the VC driver use the new keyboard table as the private table 
; for keyboard 1. 

MOVL #<IO$C_QV.LOAD_KEY_TABLE>, RO 

IQIOW.S CHAN = KBD.CHANl, - 

FUNC = #I0$_SETM0DE, - 
PI * (RO). - 

P2 = #KB_LAYOUT.TBL_LEN, - 
P3 * #KB.LAYOUT_TBL 
BLBS R0.5$ 

BRW ERROR 

5$: RSB 

; Generate a new keyboard table using macros. This table will define 
; the layout of the characters on the workstation keyboard. 

VCIKEYINIT KB.LAYOUT_TBL ; Generate the table 

; Make any changes to the table here. Because VC$KEYINIT was used to generate 
; the table, only the characters that must be changed need to be specified. 

; For example, if the "A” key will still be the "A” key in the new layout 
; and the various combinations of shift/control/lock are to remain the same, it 
; need not be specified again. (Note that the key definitions do not have to 
; be in order.) 


; Change the keyboard layout 
; On keyboard channel 1 


Keyboard table size 
New keyboard table 
Check for success 
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VC$KEY 1, <-a/! />, <^xOBO>, <^xOFF>. <‘‘xOFF>. - 

<“a/!/>,<^xOBO>,<^xOFF>.<^xOFF> 

VC$KEY 2,<“a/l/>,<-a/+/>.<-xOFF>.<^xOFF>,- 

<“a/l/>,<^a/+/>.<^XOFF>.<“XOFF> 

VC$KEY 3. <-a/2/>. <^a/''/>, <“x000>. <^x000>. - 

<“a/2/>. <“a/'7>. <“x000>. <'‘x000> 

VC$KEY 4.<^a/3/>. <^&/*/> .<“x01B>.<^x01B>.- 

<^a/3/>, <^a/*/>, <'‘x01B>. <^x01B> 

VC$KEY 5, <^a/4/>. <^xOE7>. <'‘x01C>, <^x01C>, - 

<-a/4/>.<“xOE7>.<-x01C>,<*x01C> 

VC$KEY 7.<“a/6/>.<“a/&/>.<-x01E>.<^x01E>.- 

<^a/6/>,<“a/&/>.<-x01E>,<^x01E> 

VCIKEY 8.<^a/7/>.<^x02F>.<-x01F>.<-x01F>.- 

<*a/7/>,<“x02F>,<^x01F>.<^x01F> 

VC$KEY 9.<-a/8/>.<“a/(/>.<-x07F>.<"x07F>.- 

<^a/8/>.<^a/(/>.<“x07F>.<“x07F> 

VC$KEY 10.<^a/9/>.<"a/)/>.<^xOFF>.<-xOFF>,- 

<^a/9/>.<"a/)/>.<^xOFF>.<^xOFF> 

VC$KEY 11,<"a/0/>. <^&/^/>,<^xOFF>. <"xOFF>.- 

<^a/0/>.<^a/=/>.<^xOFF>.<^xOFF> 

VC$KEY 12.<-x081>.<^a/?/>,<^x0FF>,<^x0FF>.- ; Diacritical (») 

<^x081>,<^a/?/>,<^xOFF>.<*xOFF> 

VC$KEY 13,<"x082>,<"x083>,<"x01E>,<"x01E>,- ; Diacriticals (‘ ") 

<“X082>,<*x083>,<^xOFF>.<^xOFF> 

VC$KEY 19.<-a/z/>,<"a/Z/>,<^x01A>.<^x01A>.- 

<^a/ 2 />,<^a/Z/>,<^x01A>.<^x01A> 

VCSKEY 24, <*xOE8>, <^xOFC>, <'*xOFF>. <'‘xOFF>, - 

<*xOE8>,<^xOFC>,<^xOFF>,<^xOFF> 

VC$KEY 25,<^x080>,<*x084>.<^x0FF>.<^x0FF>.- ; Diacriticals (" “) 

<^x080>,<^x084>,<^xOFF>,<^xOFF> 

VC$KEY 35,<-xOE9>,<"xOF6>,<-xOFF>,<^xOFF>,- 
<^xOE9>, <‘'xOF6>, <“xOFF>, <*xOFF> 

VC$KEY 36,<-xOEO>,<-xOE4>,<^xOFF>.<^xOFF>,- 

<*xOEO>,<“xOE4>,<^xOFF>.<“xOFF> 

VC$KEY 37, <“a/$/>, <‘‘xOA3>, <^xOFF>, <^xOFF>. - 

<*a/!/>,<*xOBO>,<*xOFF>,<*xOFF> 

VC$KEY 46.<“a/./>,<“a/;/>,<^xOFF>.<^xOFF>,- 
<"a/./>,<^a/;/>,<“xOFF>,<“xOFF> 

VC$KEY 47,<“a/./>,<“a/:/>,<^xOFF>,<^xOFF>.- 

<“a/. />, <'‘a/: />, <^xOFF>, <'‘xOFF> 

VC$KEY 48.<^a/-/>,<*a/_/>,<-xOFF>,<^xOFF>,- 

<*a/-/>,<^a/_/>,<^xOFF>,<^xOFF> 

VC$KEY 39. <^a/y/>. <'‘a/Y/>. <-x019>, <“x019>, - 

<'‘a/y/>. <*a/Y/>. <^x019>. <^x019> 

VC$KEYEND KB_LAYOUT.TBL_LEN ; End the table, 

; Eind determine its length 
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■SBTTL SET_C0MP0SE3_TABLE - SET UP A THREE-STROKE COMPOSE TABLE 

+ + 


FUNCTIONAL DESCRIPTION: 

Set up a private three-stroke compose table on keyboard channel 1. 

INPUT PARAMETERS: 

NONE 

OUTPUT PARAMETERS: 

NONE 


SET_C0MP0SE3^TABLE: 


Request that the VC driver use the new three-stroke compose table as the 
private table for keyboard 1. 


5$: 


MOVL #<I0$C_QV_L0AD_C0MP0SE_TABLE>, RO 

$QI0W^S CHAN = KBD_CHAN1, - 

FUNC = #I0$_SETM0DE. - 
Pi = (RO). - 

P4 = #C0MP0SE3_TBL_LEN. - ; 

P6 = #C0MP0SE3_TBL ; 

BLBS R0.5$ ; 

BRW ERROR 

RSB 


; Ch 2 Lnge the compose table 
: On keyboard channel 1 


Three-stroke table size 
New three-stroke table 
Check for success 


Generate a new three-stroke compose table. This table will define the new 
compose sequences for a keyboard region (This example shows a subset of 
the standard three-stroke compose sequences - the complete default 
three-stroke table is in Appendix G.) 

VC$COMPOSE_KEYINIT C0MP0SE3_TBL ; Generate an empty table 


Fill the table here. 


VCSCOMPOSE.KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VCICOMPOSE.KEY 

VC$C0MP0SE_KEY 


<"a/A/>,<“a/"/>,,<"xc4> 
<"a/A/>,<"a/V>,,<"xcl> 
<"a/A/>,<"a/*/>,,<"xc5> 
<^a/A/>,<^a/A/>.<«> 
<^a/A/>.<^a/E/>,,<^xc6> 
<"a/A/>,<"a/"/>,,<"xc2> 
<"a/A/>, <"a/_/>,, <‘‘xaa> 
<"a/A/>,<"a/‘,<"xcO> 
<“a/A/>,<^a/~/>,,<^xc3> 
<'‘a/A/>,<“x80>,,<“xc4> 
<"a/A/>,<"xbO>,,<*xc5> 


VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 


<“a/C/>,<*a/,,<"xc7> 
<"a/C/>,<"a\/\>,,<"xa2> 
<“a/C/>,<“a/0/>,,<"xa9> 
<"a/C/>, <'‘a/0/>,, <"xa9> 
<“a/C/>,<^a/I/>..<^xa2> 


Order sensitive 


VC$COMPOSE_KEYEND C0MP0SE3_TBL_LEN ; End the table. 

; and determine its length 
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.SBTTL SET^C0MP0SE2>TABLE - SET UP A TWO-STROKE COMPOSE TABLE 

++ 


FUNCTIONAL DESCRIPTION: 


Set up a private two-stroke compose table on keyboard channel 1. 

INPUT PARAMETERS: 

NONE 


OUTPUT PARAMETERS: 
NONE 


SET^C0MP0SE2_TABLE: 


Request that the VC driver use the new two-stroke compose table as the 
private table for keyboard 1. 


6 $: 


MOVL #<I0$C.QV.L0AD_C0MP0SE.TABLE>. RO 

IQIOW^S CHAN = KBD.CHANl, - ; 

FUNC * #I0$_SETM0DE, - 
PI = (RO). - 

P2 = #C0MP0SE2_TBL.LEN, - ; 

P3 * #C0MP0SE2_TBL ; 

BL6S R0.5$ : 

BRW ERROR 

RSB 


; Change the compose table 
On keyboard channel 1 


Two-stroke table size 
New two-stroke table 
Check for success 


Generate a new two-stroke compose table. This table will define the new 
compose sequences for a keyboard region (This example actually shows the 
default table of two-stroke compose sequences). 

VC$COMPOSE_KEYINIT C0MP0SE2.TBL.C0MP0SE,2=YES 


; Diaeresis mark 

VC$C0MP0SE.KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VCICOMPOSE.KEY 

VC$C0MP0SE.KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VCICOMPOSE.KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE«KEY 

VC$COMPOSE_KEY 

VC$C0MP0SE_KEY 


<^x80>,<^a/ />,<"> 
<*x80>,<"a/A/>,,<"xc4> 
<^x80>,<^a/E/>,,<^xcb> 
<^x80>,<^a/I/>,.<^xcf> 
<^x80>, <^a/0/>., <'‘xd6> 
<"x80>, <*a/U/>,, <'‘xdc> 
<^x80>, <'‘a/Y/>., <^xdd> 
<^x80>,<"a/a/>.,<^xe4> 
<“x80>,<*a/e/>,,<"xeb> 
<^x80>,<^a/i/>,,<^xef> 
<^x80>.<^a/o/>,,<*F6> 
<"x80>.<"a/u/>,,<*xfc> 
<‘'x80>, <“a/y/>,. <*xfd> 
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VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VCICOMPOSE.KEY 

VCICOMPOSE.KEY 

VCICOMPOSE.KEY 

VCICOMPOSE.KEY 

VC$COMPOSE_KEY 

VCICOMPOSE^KEY 

VCICOMPOSE^KEY 


<^x81>.<^a/ />,<»> 
<"x81>,<*a/A/>,,<"xcl> 
<^x81>,<^a/E/>..<^xc9> 
<"x81>,<*a/I/>,,<"xcd> 
<"x81>,<"a/0/>,,<^xd3> 
<"x81>,<"a/U/>,,<"xda> 
<"x81>,<"a/a/>,,<"xel> 
<"x81>,<"a/e/>.,<“xe9> 
<"x81>,<"a/i/>,,<"xed> 
<"x81>,<"a/o/>., <"xf3> 
<'*x81>,<"a/u/>, ,<‘'xfa> 


VC$COMPOSE_KEY 

VC$COMPOSE_KEY 

VC$COMPOSE_KEY 

VC$COMPOSE_KEY 

VC$COMPOSE_KEY 

VC$COMPOSE_KEY 

VC$COMPOSE_KEY 

VCICOMPOSE.KEY 

VC$COMPOSE_KEY 

VC$COMPOSE.KEY 

VC$COMPOSE_KEY 


<^x82>,<‘‘a/ />,<*> 
<"x82>,<"a/A/>, ,<'‘xcO> 
<“x82>,<*a/E/>..<^xc8> 
<*x82>,<*a/I/>.,<"xcc> 
<‘‘x82>.<^a/0/>. .<''xd2> 
<^x82>, <“a/U/>,, <‘‘xd9> 
<"x82>,<"a/a/>,,<"xeO> 
<“x82>,<"a/e/>,.<“xe8> 
<'‘x82>, <"a/i/>,. <"xec> 
<"x82>,<"a/o/>,,<*xl2> 
<*x82>,<^a/u/>.,<^xf9> 


VCICOMPOSE.KEY 

VCICOMPOSE.KEY 

VC$COMPOSE_KEY 

VCICOMPOSE.KEY 

VC$COMPOSE_KEY 

VC$COMPOSE_KEY 

VC$COMPOSE_KEY 

VCICOMPOSE.KEY 

VC$COMPOSE_KEY 

VC$COMPOSE_KEY 

VC$COMPOSE.KEY 


<^x83>,<*a/ />,<*> 
<'‘x83>, <^a/A/>,, <'‘xc2> 
<^x83>,<^a/E/>,,<^xca> 
<"x83>, <"a/I/>,, <"xce> 
<“x83>. <“a/0/>,. <'‘xd4> 
<^x83>,<^a/U/>..<^xdb> 
<"x83>,<"a/a/>,,<"xe2> 
<"x83>.<"a/e/>,,<"xea> 
<“x83>.<"a/i/>,,<"xee> 
<"x83>,<"a/o/>,,<"xf4> 
<“x83>,<"a/u/>,,<“xfb> 


VC$COMPOSE_KEY 

VC$COMPOSE_KEY 

VC$COMPOSE_KEY 

VCICOMPOSE.KEY 

VC$COMPOSE_KEY 

VC$COMPOSE_KEY 

VCSCOMPOSE.KEY 

VC$COMPOSE_KEY 


<^x84>,<^a/ />.<"> 
<^x84>.<^a/A/>.,<^xc3> 
<^x84>,<“a/N/>..<^xdl> 
<"x84>, <"a/0/>,,<‘‘xd6> 
<'‘x84>, <"a/a/>,, <"xe3> 
<*x84>,<^a/n/>.,<"xfl> 
<*x84>,<^a/o/>..<^xf6> 
<*x84>,<"a/u/>,,<"xfc> 


VC$COMPOSE_KEY <"x85>,<^a/ />..<^xbO> 
VCICOMPOSE.KEY <^x86>.<^a/A/>..<^xc6> 
VC$COMPOSE_KEY <^x86>, <‘‘a/a/>.. <^xe6> 
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VC$COMPOSE_KEYEND C0MP0SE2_TBL_LEN 


; End the table. 

: and determine its length 
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.SBTTL SET.KBDAST - SET UP KEYBOARD REGIONS 


FUNCTIONAL DESCRIPTION: 

Enable several keyboard regions. 

INPUT PARAMETERS: 

NONE 

OUTPUT PARAMETERS: 

NONE 


SET.KBDAST: 

$ASSIGN_S DEVNAM=WS_DEVNAM.- 
CHAN=KBD_CHAN2 
BLBS R0.10$ 

BRW ERROR 

10$: MOVL #IO$C_QV_MODIFYKB,RO 

$QIOW_S CHAN=KBD_CHAN1.- 

FUNC=#IO$_SETMODE,- 
P1=(R0).- 
P2*#P2_BL0CK1,- 
P3=#P33L0CK 
BLBS R0.20$ 

BRW ERROR 

20$: MOVL #IO$C_QV_ENAKB.RO 

$QIOW_S CHAN=KBD_CHAN2.- 

FUNC=#IO$_SETMODE,- 
P1=(R0).- 
P2=#P2«BL0CK2.- 
P3=#P3_BL0CK 
BLBS R0,30$ 

BRW ERROR 

30$: RSB 

P2_BL0CK1: 

.LONG KBD.AST 
.LONG ACKl 

.LONG 
.LONG 

ACKl: .ASCID 

P2_BL0CK2: 

.LONG 
.LONG 
.LONG 
.LONG 

ACK2: .ASCID 

P3_BL0CK: 

.LONG 
.LONG 
.LONG 
.LONG 


; Assign keyboard channel 2 using 
; logical name and channel number 
; Check for success 

; Modify the keyboard 
; On keyboard channel 1 


; AST specification block 
; Control AST block 
; Check for success 

; Enable a keyboard 
; On keyboard channel 2 


AST specification block 
Control AST block 
Check for success 


AST specification block 1 
Keyboard AST address 
AST parameter 
0 ; AST delivery mode 

CHARACTER ; Input token 

/INPUT ACKNOWLEDGED CHANNEL 1/ ; Acknowledgment 1 

; AST specification block 2 

KBD_AST 

ACK2 

0 

CHARACTER 

/INPUT ACKNOWLEDGED CHANNEL 2/ 


CTL.AST 

0 

0 

0 


Control AST specification block 

Control AST address 

AST parameter 

AST delivery mode 

Must be zero 
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.SBTTL SET.BUTTONAST - ENABLE POINTER BUTTON REGION 


FUNCTIONAL DESCRIPTION: 

Enable a pointer button region, and specify eui AST address. 

INPUT PARAMETERS: 

NONE 

OUTPUT PARAMETERS: 

NONE 


SET_BUTTONAST: 

lASSIGN^S DEVNAM=WS^DEVNAM.- 

Assign a button channel using 


CHAN=BUT_CHAN 

logical n£Lffle and channel numb( 

BLBS 

R0.10$ 

Check for success 

BRW 

ERROR 


10$: MOVL 

#IO$C.QV_ENABUTTON,R0 

Enable button transitions 

$QIOW. 

.S CHAN=BUT_CHAN,- 

On the button channel 


FUNC=#IO$_SETMODE.- 

P1=(R0).- 

P2=#BUT_BL0CK,- 

AST specification 


P6=#BUT_REGI0N 

Associated button region 

BLBS 

R0.20$ 

Check for success 

BRW 

ERROR 


20$: RSB 

BUT.BLOCK: 


Button AST specification block 

.LONG 

BUT.AST 

AST address 

.LONG 

0 

AST parameter 

.LONG 

0 

Access mode 

.LONG 

BUTTON 

Button information longword 

BUT.REGION: 


Button AST region 

.LONG 

20 

Lower left corner (ADC) 

.LONG 

20 


.LONG 

300 

Upper right corner (ADC) 

.LONG 

300 
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.SBTTL SET.FNKEYAST - ENABLE F6 FUNCTION KEY 


FUNCTIONAL DESCRIPTION: 

Enable a function key. and specify an AST address. 

INPUT PARAMETERS: 

NONE 

OUTPUT PARAMETERS: 

NONE 


SET_FNKEYAST: 



$ASSIGN_S DEVNAM=WS_DEVNAM.- ; 

Assign function key channel using 



CHAN=FNKEY_F5_CHAN ; 

logical name eind channel number 


BLBS 

R0.10$ : 

Check for success 


BRW 

ERROR 


10$: 

MOVL 

#IO$C,QV.ENAFNKEY.RO ; 

Enable function key 


$QIOW_S 

CHAN=FNKEY_F5.CHAN,- ; 

FUNC=#IO$_SETMODE,- 

On function key channel 



P1=(R0),- 

P2=#FNKEY.BL0CK.> ; 

AST specification block 



P3=#QV$M_KEY_F6 ; 

Modifier indicating F5 key 


BLBS 

R0.30$ ; 

Check for success 


BRW 

ERROR 


30$: 

RSB 



FNKEY3L0CK: 


Function key AST specification block 


.LONG 

F6«AST ; 

AST address 


.LONG 

F6_ACK ; 

AST parameter 


.LONG 

0 ; 

Access mode 


.LONG 

CHARACTER ; 

Input token 

F5_ACK: 

.ASCID 

/FUNCTION KEY F5 HAS BEEN 

PRESSED/ : Acknowledgment message 


.SBTTL 

SET.MOUSEAST - ENABLE POINTER MOVEMENT REGION 


++ 


FUNCTIONAL DESCRIPTION: 


Enable pointer movement ASTs for a region. 


INPUT PARAMETERS: 
NONE 

OUTPUT PARAMETERS: 
NONE 


SET.MOUSEAST: 

$ASSIGN.S DEVNAM=WS_DEVNAM,- 
CHAN=MOUSE.CHAN 
BLBS R0.10$ 

BRW ERROR 


Assign pointer channel using 
logical name and channel number 
Check for success 
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10$: MOVL #IO$C_QV,MOUSEMOV.RO 

$QI0W_S CHAN^MOUSE.CHAN,- 

FUNC=#I0$.SETM0DE.- 
P1=(R0).- 
P2=#M0USE_BL0CK.- 
P6=#M0USE.REGI0N 
BLBS R0.20$ 

BRW ERROR 

20$: RSB 

MOUSE.BLOCK: 

.LONG MOUSE.AST 
.LONG MOUSE.ACK 
-LONG 0 
.LONG M0USE_XY 

MOUSE.REGION: 

.LONG 400 
.LONG 400 
.LONG 800 
.LONG 800 

MOUSE.ACK: 

.ASCID 


Enable pointer movement 
On pointer channel 

AST specification block 
Associated region 
Cl^eck lor success 


Pointer region AST specification block 

AST address 

AST parameter 

Access mode 

New cursor position 

Pointer region 

Lower left corner (ADC) 


Upper right corner (ADC) 


/POINTER MOVEMENT DETECTED/ ; Acknowledgment message 


i 


( 


.SBTTL SIMULATE.INPUT - SIMULATE INPUT ON KEYBOARD 2 


FUNCTIONAL DESCRIPTION: 

Simulate keyboard input on keyboard channel 2. 

INPUT PARAMETERS: 

NONE 

OUTPUT PARAMETERS: 

NONE 


SIMULATE.INPUT: 


MOVL 

#IO$C_QV_SIMOLATE.RO 

; Simulate keyboard input 

$QIOW.S 

CHAN=KBD_CHAN2.- 

FUNC=#IO$_SETMODE.- 

P1«(R0).- 

; On keyboard channel 2 


P2=#SIM_ACK,- 

; Acknowledgment 


P3=#0 

; No pointer repositioning 

BLBS 

R0.20$ 

; Check for success 

BRW 

20$: RSB 

ERROR 


SIM.ACK: 

.ASCID 

/This input SIMULATED 

on chan 2./ ; Acknowledgment message 
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• SBm 0NE_SH0T_AST - ONE.SHOT AST ROUTINE 


FUNCTIONAL DESCRIPTION: 

This is the AST routine specified by the ’one-shot* read QIO. 

INPUT PARAMETERS: 

NONE 

OUTPUT PARAMETERS: 

NONE 


ONE_SHOT_AST: 

.WORD 

PUSHL 

CALLS 

BLBS 

BRW 

4(AP) 

#1,GUIB$PUT_LINE 
RO. 10$ 

ERROR 

; Send acknowledgment message 

10$: 

PUSHAL 

CALLS 

DESCl 

#1.G^LIB$PUT_LINE 

; Send character typed, 

; descriptor points to lOSB 


RET 




.SBTTL 

MOUSE_AST “ POINTER 

AST ROUTINE 




FUNCTIONAL DESCRIPTION: 

This is the AST routine specified by the enable pointer movement QIO. 
INPUT PARAMETERS: 

POINTER_XY - Contains the current X and Y coordinates for the pointer. 

OUTPUT PARAMETERS: 

NONE 


M0USE_AST: 

.WORD 
PUSHL 
CALLS 
BLBS 
5$: BRW 

10$: RET 


4(AP) ; Send acknowledgment message 

#1,G''LIB$PUT_LINE 

RO. 10$ 

ERROR 
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.SBTTL KBD_AST - KEYBOARD AST ROUTINE 
.SBTTL F5_AST - FUNCTION KEY F5 AST ROUTINE 


FUNCTIONAL DESCRIPTION: 


This is the AST routine specified by the enable keyboard QIO and 
by the enable function key F5 QIO. 

INPUT PARAMETERS: 

NONE 

OUTPUT PARAMETERS: 

NONE 


KBD.AST: 

F5_AST: 


5$: 

.WORD 

PUSHL 

CALLS 

BLBS 

BRW 

4(AP) 

#1.G-LIB$PUT_LINE 

RO. 10$ 

ERROR 

; Send acknowledgment message 

10$: 

CMPW 

BNEQ 

BSBW 

BRB 

#KEY$C_F5.CHARACTER 
20$ 

CYCLE.KBD 

40$ 

; Was F5 typed? 

; Cycle the keyboard list 
: and exit 

20$: 

PUSHAL 

CALLS 

BLBC 

DESC 

#1.G“LIB$PUT_LINE 

R0.5$ 

; Send character typed 


CMPB 

BNEQ 

BSBW 

BRB 

#-A/C/.CHARACTER 

30$ 

CYCLE.KBD 

40$ 

; Was a "C" typed? 

; Cycle the keyboard list 

30$: 

CMPB 

BNEQ 

$SETEF. 

#-A/F/.CHARACTER 

40$ 

.S EFN=#2 

; Was an "F” typed? 

; Yes, exit program 

40$: 

RET 




.SBTTL 

CTL.AST - CONTROL AST 

ROUTINE 


++ 


FUNCTIONAL DESCRIPTION: 


This is the control AST routine. 

INPUT PARAMETERS: 

NONE 
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OUTPUT PARAMETERS: 
NONE 
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CTL.AST: 

.WORD 

PUSHAL CYCLE_ACK 
CALLS #1.G*L1B$PUT_LINE 
BLBS RO. 10$ 

5$: BRW ERROR 

10$: RET 


Send acknowledgment message 


CYCLE_ACK: 

.ASCID /KEYBOARD HAS BEEN CYCLED/ ; Acknowledgment message 


.SBTTL BUT.AST - BUTTON AST ROUTINE 


FUNCTIONAL DESCRIPTION: 

This is the AST routine specified by the enable pointer movement QIO. 
INPUT PARAMETERS: 

BUTTON - Status of the pointer buttons. 

OUTPUT PARAMETERS: 

NONE 


BUT_AST: 



.WORD 




CMPW 

#KEY$C.BUTT0N^1.BUTTON 

; Was BUTTON 1 changed? 


BNEQ 

10$ 

; (predefined constant) 


PUSHAL 

BUTl^ACK 



BRB 

50$ 


10$: 

CMPW 

#KEY$C_BUTT0N_2,BUTTON 

; Was BUTTON 2 changed? 


BNEQ 

20$ 



PUSHAL 

BUT2_ACK 



BRB 

50$ 


20$: 

CMPW 

#KEY$C_BUTT0N_3.BUTTON 

: Was BUTTON 3 changed? 


BNEQ 

100$ 



PUSHAL 

BUT3_ACK 


80$: 

CALLS 

#1.G"LIB$PUT_LINE 

; Send correct acknowledgment 


BLBS 

R0.60$ 



BRW 

ERROR 


60$: 

PUSHAL 

BUTUP.ACK 

; Assume button was released 


BBC 

#31,BUTTON.70$ 

; If clear then button released 


PUSHAL 

BUTDOWN.ACK 

; Otherwise, button was depressed 

70$: 

CALLS 

#1.G'‘LIB$PUT^LINE 

; Send acknowledgment message 


BLBS 

R0.100$ 



BRW 

ERROR 


100$: 

RET 
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; Acknowledgment messages 

BUTl.ACK: 

.ASCID /POINTER BUTTON 1 TRANSITION HAS BEEN DETECTED/ 
BUT2.ACK: 

.ASCID /POINTER BUTTON 2 TRANSITION HAS BEEN DETECTED/ 
BUT3.ACK: 

.ASCID /POINTER BUTTON 3 TRANSITION HAS BEEN DETECTED/ 
BUTUP.ACK: 

.ASCID /BUTTON IS UP/ 

BUTDOWN.ACK: 

.ASCID /BUTTON IS DOWN/ 


.SBTTL CYCLE.KBD - CYCLE KEYBOARD REGION 

++ 

FUNCTIONAL DESCRIPTION: 

This routine cycles the keyboard to the next keyboard region. 

INPUT PARAMETERS: 

NONE 

OUTPUT PARAMETERS: 

NONE 


CYCLE.KBD: 

MOVL #<IO$C.QV.ENAKB!IO$M_QV^CYCLE>,RO ; Use keyboard cycle modifier 

IQIOW.S CHAN=KBD.CHAN1.- ; On keyboard channel 1 

FUNC=#IO$_SETMODE.- 
Pl= (RO) 

BLBS R0,40$ ; Check for success 

BRW ERROR 

RSB 

.END START 


0-23 


40 $: 






Appendix E 
Keyboard Table Macros 


.SBTTL VC$KEYINIT - Macro to generate keyboard table 

++ 

VC$KEYINIT - Initializes the keyboard table 

VC$KEY - Generates a key table entry for the given position 

This macro defines a given key entry for the keyboard position. 

This entry contains the ASCII translation for the lowercase character, 
uppercase character, control (CTRL) for this position, and shift control 
for this position. In addition it will generate a lock state for this 
position including the character to be used when lock is detected, when 
shift lock is detected, when control lock is detected, and when control 
shift lock is detected. 


.Macro VC$KEY POSITION,LOWER,SHIFT,CTRL,SHIFT.CTRL,LOCK,- 
SHIFT.LOCK,CTRL.LOCK,SHIFT_CTRL^LOCK 
. =BASE+«P0SITI0N-1>*8> 

.BYTE LOWER ; Lowercase character 

.IF BLANK,<SHIFT> ; Shift (uppercase) character 

. BYTE L0WER&<^C<1@5» 

.IFF 

. BYTE SHIFT 
.ENDC 

.IF BLANK,<CTRL> ; Control key and character key 

. BYTE L0WER&<^C<3@5» 

.IFF 

. BYTE CTRL 
.ENDC 
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. IF BLANK,<SHIFT_CTRL> 

. BYTE LGWER&<^C<3®5» 

.IFF 

.BYTE SHIFT.CTRL 
.ENDC 

.IF BLANK.<L0CK> 

. BYTE L0WER&<^C<1®5» 

.IFF 

.BYTE LOCK 
.ENDC 

.IF BLANK.<SHIFT_LOCK> 

. BYTE L0WER&<^C<1®5» 

.IFF 

.BYTE SHIFT^LOCK 
.ENDC 

.IF BLANK.<CTRL_L0CK> 

. BYTE L0WER&<^C<3®5» 

.IFF 

.BYTE CTRL.LOCK 
.ENDC 

. IF BLANK.<SHIFT_CTRL_LOCK> 
. BYTE L0WER&<^C<3@5» 

.IFF 

. BYTE SHIFT_CTRL_LOCK 

.ENDC 

.ENDM VC$KEY 


Shift, control and character key 
Usually same as control 


Lock and character keys 
Usually the same as shift 


Shift, lock and character keys 
Usually the same as shift 


Control, lock and character keys 
Usually the same as control 


Shift, control, lock & char keys 
Usually the same as control 
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.Macro VC$KEYINIT NAME,VERSI0N=1,INTERNAL 
• SAVE 

•PSECT $$$117_’NAME.LONG 
. IF NB INTERNAL 

•long 2 ; ♦ Used for building internal driver table * 

.ENDC 
MAXKEY=49 
TBL.START=. 

NAME==. 

.QUAD VERSION 

; Allocate space for the table. Pre-initialize it to known values (-1). 
BASE=. 

.REPEAT MAXKEY-1 
.LONG -1,-1 
.ENDR 
ENDBASE=. 

; Initialize the table to the North American keyboard. 

VC$KEY 1, <^a/ V> . <''a/V>. <^xle>, <^xle>. - 
<^a/ V> , <"a/''/>, <^xle>, <^xle> 

VC$KEY 2. <''a/l/>, <''a/! />. <^xOFF>, <^xOFF>, - 
<^a/l/>, <'‘a/! />. <^xOFF>, <^xOFF> 

VC$KEY 3. <^a/2/>, <'^a/(a/>, <^x00>. <^x00>, - 
<''a/2/>, <^a/@/>, <''x00>, <^x00> 

VC$KEY 4. <^a/3/>, <^a/#/>, <'‘xlb>. <^xlb>. - 
<^di/3 />. <^a/#/>. <^xlb>, <^xlb> 

VC$KEY 5,<^a/4/>,<^a/$/>,<^xlc>,<^xlc>,- 
<"a/4/>,<"a/$/>,<"xlc>.<"xlc> 

VC$KEY 6. <^a/5/>, <^a/y./>. <'‘xld>, <''xld>, - 
<"a/5/>,<"a/%/>,<"xld>.<"xld> 

VC$KEY 7.<^a/6/>.<^a/^/>.<^xle>.<^xle>,- 
<^a/6/>,<^a/^/>.<^xle>,<^xle> 

VC$KEY 8.<"a/7/>,<^a/&/>,<^xlf>.<^xlf>,- 
<"a/7/>,<"a/&/>,<"xlf>,<"xlf> 
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VC$KEY 9,<*a/8/>,<-a/*/>,<-x7f>,<“x7f>,- 
<"a/8/>.<‘a/*/>.<“x7f>,<‘x7f> 
VC$KEY 10. <*a/9/>, <*a/ (/>, <'‘xOFF>, <*xOFF>, 
<'a/9/>,<*a/(/>.<“xOFF>,<~xOFF> 
VC$KEY 11,<-a/0/>.<*a/)/>.<‘xOFF>,<‘xOFF>, 
<"a/0/>.<*a/)/>,<'xOFF>.<"xOFF> 
VC$KEY 12,<'a/-/>,<*a/_/>.<‘xlf>,<-xlf>,- 
<"a/-/>.<"a/_/>,<*xlf>,<~xlf> 
VC$KEY 13,<'a/=/>.<*a/+/>.<‘xOFF>,<'xOFF>, 
<"a/=/>.<*a/+/>,<*xOFF>,<*xOFF> 
VC$KEY 14, <*a/q/>. <‘a/Q/>. <'xll>. <''xll>, - 
. ,<"xll>,<‘xll> 

VC$KEY 15,<'A/w/>,<‘a/W/>.<‘xl7>.<'xl7>.- 
, .<"xl7>,<‘xl7> 

VC$KEY 16,<‘A/e/>.<“a/E/>.<'x05>,<'x05>.- 
, ,<~x05>,<‘x05> 

VC$KEY 17.<'A/r/>.<*a/R/>.<*xl2>.<‘xl2>.- 
, ,<~xl2>,<~xl2> 

VC$KEY 18, <'A/t/>, <*a/T/>, <‘xl4>. <''xl4>, - 
. .<~xl4>.<''xl4> 

VC$KEY 19,<‘A/y/>,<*a/Y/>,<-xl9>,<*xl9>.- 
, ,<~xl9>,<~xl9> 

VC$KEY 20,<‘A/u/>,<"a/U/>.<'xl5>,<~xl5>.- 
, ,<“xl5>,<~xl5> 

VC$KEY 21,<“A/i/>,<'a/I/>.<~x09>.<~x09>.- 
, ,<‘x09>,<''x09> 

VC$KEY 22. <‘k/o/>, <-a/0/>.<-xOF>.<‘xOF>,- 
. ,<*x0F>,<''x0F> 

VC$KEY 23.<“A/p/>.<'a/P/>,<*xl0>,<‘xl0>,- 
, ,<‘xl0>,<''xl0> 

VC$KEY 24, <‘A/ [/>. <'a/{/>. <*xlb>. <''xlb>, - 
<*a/ [/>, <"a/{/>, <''xlb>, <*xlb> 
VC$KEY 25. <*A/] />. <'‘a/}/>, <''xld>, <‘xld>. - 
<"a/] />, <“a/}/>, <‘'xld>, <*xld> 
VC$KEY 26,<*A/a/>.<*a/A/>.<'x01>.<~x01>.- 
. .<‘x01>,<‘x01> 

27,<"A/s/>.<“a/S/>.<~xl3>.<~xl3>.- 
, .<'xl3>,<~xl3> 


VC$KEY 
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VC$KEY 28.<'A/d/>.<~a/D/>,<‘x04>.<*x04>.- 
, ,<'x04>,<~x04> 

VC$KEY 29,<*A/f/>,<~a/F/>,<‘x06>,<-x06>,- 
, ,<*x06>.<*x06> 

VC$KEY 30, <~k/g />. <-'a/G/>. <*x07>. <‘x07>, - 
, .<*x07>,<'x07> 

VC$KEY 31.<*A/h/>.<'a/H/>.<'x08>.<'x08>.- 
, .<‘x08>,<'‘x08> 

VC$KEY 32,<‘A/j/>,<*a/J/>,<"xOA>.<"xOA>.- 
. ,<*x0A>,<'x0A> 

VC$KEY 33.<*A/k/>.<‘a/K/>,<"xOB>,<*xOB>,- 
, ,<"x0B>,<~x0B> 

VC$KEY 34, <'A/l/>, <'‘a/L/>, <‘xOC>, <'xOC>, - 
, ,<"x0C>,<“x0C> 

VC$KEY 35,<'x03B> ,<'&/:/>, <*xOFF>,<*xOFF>.- 
<“x03B>.<“a/:/>.<“xOFF>,<“xOFF> 
VC$KEY 36,<'a/’/>,<*a/"/>,<"xOFF>,<‘xOFF>,- 
<~a/ ’ />, <“a/"/>. <“xOFF>, <'‘xOFF> 
VC$KEY 37,<'a/\/>,<“a/I/>,<‘xlc>,<'xlc>.- 
<*a/\/>.<*a/I/>,<‘xlc>.<“xlc> 
VC$KEY 38,<*x3c>.<*x3e>.<*xOFF>,<‘xOFF>,- 
<''x3c>. <''x3e>, <“xOFF>, <*xOFF> 
VC$KEY 39, <-'A/z/>. <“a/Z/>. <“xlA>, <*xlA>, - 
, ,<“xlA>,<"xlA> 

VC$KEY 40. <'A/x/>. <'‘a/X/>, <"xl8>, <*xl8>, - 
, ,<“xl8>,<"xl8> 

VC$KEY 41. <*A/c/>. <''a/C/>, <"x03>, <‘x03>, - 
. ,<“x03>,<“x03> 

VC$KEY 42, <*A/v/>. <'‘a/V/>, <‘xl6>, <'xl6>, - 
. .<"xl6>.<‘xl6> 

VC$KEY 43, <*A/b/>, <'‘a/B/>. <“x02>, <'x02>, - 
. ,<'x02>.<"x02> 

VC$KEY 44.<'A/n/>,<‘a/N/>,<'xOE>,<'xOE>,- 
, ,<‘x0E>,<'x0E> 

VC$KEY 45.<*A/m/>,<‘a/M/>,<'xOD>,<'xOD>.- 
, ,<*x0D>.<‘x0D> 

VC$KEY 46. <'a/. />, <'‘a/. />. <‘xOFF>, <*xOFF>, - 
<*a/./>.<*a/,/>,<‘xOFF>,<~xOFF> 
VC$KEY 47,<*a/./>.<'a/./>,<“xOFF>,<“xOFF>,- 
<*a/./>,<‘a/./>.<'xOFF>,<‘xOFF> 
VC$KEY 48.<~x2f>,<*a/?/>,<*xlf>,<‘xlf>,- 
<'x2f>,<“a/?/>,<*xlf>.<*xlf> 

.endm VC$KEYINIT 


■MACRO VC$KEYEND TABLE_SIZE 
=ENDBASE 


PC points to first byte after table 
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.IF NOT^BLANK TABLE^SIZE 

TABLE.SIZE == ENDBASE - TBL.START ;Size of table 

.ENDC 

.RESTORE 

.ENDM VC$KEYEND 
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Compose Table Macros 


This appendix contains the macros used to construct a compose table. 

.SBTTL VC$COMPOSE_KEYINI - Macro to initialize a compose sequence table 

; ++ 

; MACRO VC$COMPOSE_KEYINI - Macro to initialize a compose sequence table 


INPUTS 

NAME = TABLE NAME TO GENERATE 

C0MP0SE_2 = YES - IF THIS IS A 2 CHARACTER COMPOSE TABLE 
BLANK ’ IF A 3 CHARACTER COMPOSE TABLE 
VERSION = TABLE VERSION 

INTERNAL = YES - IF THIS MACRO IS BEING CALLED TO BUILD INTERNAL TABLE. 
BLANK - IF THIS MACRO IS BEING CALLED NORMALLY. 


NAME==. 


. Macro 
.SAVE 
.PSECT 
.IF NB 
long 
.ENDC 


. save 

.psect $$$118_*NAME*_B 
ext_*name=. 

.restore 


Used by driver. 


Save attributes 
Go to other psect 
Save base address 
Restore attributes 


NOT for regular table *** 


VC$COMPOSE_KEYINIT NAME,C0MP0SE.2,VERSI0N=1,INTERNAL 

$$$118_*NAME»_A 
INTERNAL 
2 
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•LONG VERSION 
.IF NB C0MP0SE_2 
i=0 

DIA.TAB_*NAME=. 

.repeat <256/32> ; Get the diacritical table 

.long 0 

dia^init \i 

i=i+l 

.endr 

.ENDC 

.SBTTL VC$C0MP0SE_KEY - Macro to generate a compose table entry 

; ++ 

; MACRO VC$COMPOSE_KEY - Macro to generate a compose table entry 
; INPUTS 

; INPUT_CHAR1 = FIRST CHARACTER OF COMPOSE SEQUENCE 

; INPUT_CHAR2 = SECOND CHARACTER OF COMPOSE SEQUENCE 

; OUTPUT_SIZE = SIZE OF THE OUTPUT STRING (optional, 

; if omitted, size will be calculated) 

; OUTPUT_CHAR = OUTPUT STRING 


.Macro VC$C0MP0SE_KEY input^char1,input_char2,output_size,output.char 

.BYTE INPUT^CHARl 
.BYTE INPUT.CHAR2 
.SAVE 

.PSECT $$$118.’NAME’_B 

STR=. 

.IF BLANK <OUTPUT_SIZE> 

.BYTE 1 

.BYTE OUTPUT_CHAR 
.IFF 

.ASCIC lOUTPUT^SIZEl 
.ENDC 

.RESTORE 

.WORD STR-NAME 
.IF NB C0MP0SE_2 
I=INPUT_CHARl/32 
J=INPUT.CHAR1-<I*32> 

DIA \I,\J 
.ENDC 

.endm VC$C0MP0SE_KEY 
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++ 

MACRO VC$COMPOSE_KEYEND - Macro to end a compose table 


INPUTS 

TABLE.SIZE - (optional) Location to store size of table 


.MACRO VC$COMPOSE_KEYEND TABLE^SIZE 
.LONG -1 

.IIF NB,C0MP0SE_2. DIA.END DIA^TAB_^NAME 

.IF NB TABLE_SIZE 

TABLE_SIZE == .-name 

.psect $$$118_*NAME*_B 

TABLE_SIZE == TABLE_SIZE+<.-ext_*name> 

.ENDC 

.RESTORE 

.ENDM VC$COMPOSE_KEYEND 


If table size requested 
Get size of first psect 
Jump to other psect 
Add in size of this psect 


. ENDM VC$COMPOSE_KEYINIT 


.SBTTL MACRO DIA_INIT - Macro to generate diacritical table 

++ 

MACRO DIA_INIT - Macro to generate diacritical table 


INPUTS 

N - OFFSET INTO TABLE 


.MACRO DIA.INIT N 
DIA_*N = 0 

.MACRO DIA OFFSET.BIT^POS 

.IIF GT OFFSET-N..ERROR ; OFFSETS CANNOT BE GREATER THAN DIA^MAX 
DIA.’OFFSET=10BIT_POS!DIA_’OFFSET 
.ENDM DIA 
.MACRO DIA.GEN X 
LONG DIA.*X 
.ENDM DIA.GEN 
.MACRO DIA.END LABEL 
.SAVE 
.=LABEL 
X=0 

.REPEAT N+1 

DIA.GEN \X 

X=X+1 

.ENDR 

.RESTORE 

.ENDM DIA.END 

.ENDM DIA.INIT 
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Three-Stroke Compose Table Default Values 


This appendix contains the macro that is executed to load the default three-stroke 
compose table values. (The default two-stroke table is shown in the example in 
Appendix D.) 


VC$COMPOSE_KEYINIT qV$C0MP0SE3_TABLE 


sp !"#$•/,& ’ ( ) 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$COMPOSE_KEY 

VC$C0MP0SE_KEY 

VC$COMPOSE_KEY 

VC$COMPOSE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$COMPOSE_KEY 

VC$C0MP0SE_KEY 

VC$COMPOSE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 


. / 

<“a/ />,<‘a/"/>.<"> 

<‘a/ />.<"a/’/>.<’> 

<“a/ />,<'a/*/>,.<*xbO> 
<'a/ />.<"> 

<''a/ />,<"a/~/>,<"> 

<‘a/ />,<“xbO>,.<*xbO> 

<‘a/!/>.<"a/!/>,.<“xal> 
<‘a/!/>,<"a/P/>,,<~xb6> 
<‘a/!/>.<*a/S/>..<"xa7> 
<*a/!/>,<''a/p/>, ,<“xb6> 
<'a/!/>.<"a/s/>..<“xa7> 

<*a/"/>,<'a/ />,<"> 
<*a/"/>.<'a/A/>..<*xc4> 
<*a/"/>,<"a/E/>,.<‘xcb> 
<*a/"/>.<*a/I/>. .<''xcf> 
<*a/"/>,<''a/0/>. ,<~xd6> 
<''a/''/>.<'a/U/>, ,<*xdc> 
<~a/"/>.<*a/Y/>, ,<''xdd> 
<“a/''/>.<*a/a/>, ,<“xe4> 
<“a/"/>.<*a/e/>,,<~xeb> 
<'‘a/"/>,<''a/i/>, ,<“xef> 
<~a/"/>,<"a/o/>..<*xf6> 
<“a/"/>,<''a/u/>, ,<'‘xfc> 
<*a/"/>.<'‘a/y/>, ,<*xfd> 


* + , - 
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'V, 


VC$COMPOSE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$COMPOSE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$COMPOSE_KEY 

VC$COMPOSE_KEY 


<“a/’/>,<“a/ />.<’> 

<'a/’/>,<*a/A/>. ,<''xcl> 
<'a/7>,<‘a/E/>, .<*xc9> 
<'‘a/ ’ />, <“a/I/>,, <*xcd> 
<"a/7>.<‘a/0/>, ,<“xd3> 
<"a/’/>,<*a/U/>,,<*xda> 
<“a/’/>.<“a/a/>..<*xel> 
<‘a/’/>,<"a/e/>..<*xe9> 
<“a/’/>.<~a/i/>,,<‘xed> 
<“a/’/>.<*a/o/>,,<*xf3> 
<'‘a/’/>.<“a/u/>, ,<*xfa> 


VC$C0MP0SE_KEY <‘a/(/>,<-a/(/>,<[> 
VC$C0MP0SE_KEY <‘a/(/>.<‘a/-/>,<{> 


VC$COMPOSE_KEY <'a/) />, <'‘a/) />,<]> 
VC$C0MP0SE_KEY <*a/)/>,<'‘a/-/>,<}> 


VC$C0MP0SE_KEY <*a/*/>.<'a/ />,,<*xbO> 
VC$C0MP0SE_KEY <*a/*/>,<*a/A/>..<*xc5> 
VC$C0MP0SE_KEY <‘a/*/>.<‘a/a/>.,<*xe5> 


VC$C0MP0SE_KEY <'a/+/>.<*a/+/>.<#> 
VC$C0MP0SE_KEY <*a/+/>.<“a/-/>.,<‘xbl> 


VC$C0MP0SE_KEY <*a/./>.<*a/C/>,,<“xc7> 
VC$C0MP0SE_KEY <‘a/. />. <'‘a/c/>,. <*xe7> 


VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$COMPOSE_KEY 

VC$COMPOSE_KEY 


<*a/-/>.<“a/(/>.<{> 
<-a/-/>.<''a/)/>,<}> 
<“a/-/>,<*a/+/>,,<*xbl> 
<"a/-/>,<“a/L/>.,<*xa3> 
<*a/-/>,<'a/Y/>.,<*xa5> 
<“a/-/>,<“a/l/>,,<~xa3> 
<*a/-/>,<*a/y/>,,<*xa5> 


VC$C0MP0SE_KEY <'a/./>,<‘a/"/>..<*xb7> 


VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$COMPOSE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 


<‘a\/\>.<‘a\A>,<\> 
<*a\/\>,<'x3c>.<\> 
<*a\/\>,<'a/C/>..<~xa2> 
<"a\A>,<*a/0/>, .<"xd8> 
<‘a\/\>.<“a/U/>,,<"xb5> 
<‘a\/\>.<"a/~/>.,<“a/1/> 
<"a\/\>,<''a/c/>, ,<"xa2> 
<"a\/\>,<~a/o/>.,<“xf8> 
<“a\/\>,<“a/u/>,,<“xb5> 



order sensitive 


order sensitive 
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0123456789 :;< = >? 


VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 


<*a/0/>,<'a/C/>,.<*xa9> 
<*a/0/>,<“a/S/>,,<*xa7> 
<~a/0/>.<'a/X/>.,<*xa8> 
<*a/0/>,<'a/“/>,,<*xbO> 
<*a/0/>,<*a/c/>, ,<''xa9> 
<'‘a/0/>,<"a/s/>, ,<‘xa7> 
<*a/0/>,<*a/x/>,,<“xa8> 


VC$C0MP0SE_KEY <*a/l/>,<'a/2/>,,<'xbd> 
VC$C0MP0SE_KEY <'a/l/>,<"a/4/>,,<~xbc> 
VC$C0MP0SE_KEY <‘a/l/>.<‘a/‘/>,,<*xb9> 


VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 


<*a/2/>,<*a/*/>,.<‘xb2> 

<*a/3/>,<“a/‘/>,,<“xb3> 

<~x3c>,<*a\/\>,<\> 
<“x3c>,<'x3c>,,<~xab> 


VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 


<“a/=/>,<“a/L/>.,<"xa3> 
<*a/=/>,<“a/Y/>,,<'xa5> 
<“a/=/>,<'a/l/>,.<~xa3> 
<"a/=/>,<"a/y/>,,<“xa5> 

<*x3e>,<'‘x3e>, ,<“xbb> 


VC$C0MP0SE_KEY <'a/?/>.<"a/?/>,,<“xbf> 


order sensitive 
order sensitive 


A to Z 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 


<'a/A/>,<"a/'7>..<*xc4> 
<~a/A/>,<“a/’/>, ,<‘'xcl> 
<*a/A/>,<“a/*/>,.<“xc5> 
<'a/A/>.<'a/A/>.<@> 
<''a/A/>,<*a/E/>, ,<“xc6> 
<"a/A/>,<'a/*/>,,<“xc2> 
<*a/A/>,<“a/_/>,,<*xaa> 
<“a/A/>,<"a/‘/>.,<“xcO> 
<‘a/A/>.<"a/“/>.,<“xc3> 
<''a/A/>,<“x80>, .<“xc4> 
<“a/A/>. <“xbO>,, <''xc5> 

<'a/C/>.<"a/..<'xc7> 
<"a/C/>,<“a\/\>.,<“xa2> 
<“a/C/>,<“a/0/>,,<"xa9> 
<“a/C/>,<"a/0/>,,<~xa9> 
<“a/C/>.<"a/I/>..<*xa2> 


order sensitive 
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VC$C0MP0SE_KEY <-a/E/>,<-a/"/> 
VC$COMPOSE_KEY <‘a/E/>, <~z./ ’ /> 
VC$C0MP0SE_KEY <"a/E/>,<'a/''/> 
VC$C0MP0SE_KEY <‘a/E/>,<"a/‘/> 
VC$C0MP0SE_KEY <*a/E/>.<*x80>. 

VC$C0MP0SE_KEY <“a/I/>.<‘a/"/> 
VC$C0MP0SE_KEY <*a/I/>.<'a/’/> 
VC$C0MP0SE_KEY <'‘a/I/>, <‘a/‘/> 
VC$C0MP0SE_KEY <"a/I/>.<‘a/7> 
VC$C0MP0SE_KEY <"a/I/>,<"x80>. 

VC$C0MP0SE_KEY <‘a/L/>,<'‘a/-/> 
VC$C0MP0SE_KEY <"a/L/>,<‘a/=/> 

VC$COMPOSE_KEY <"a/N/>,<"a/"/> 

VC$COMPOSE_KEY <*a/0/>,<*a/7> 
VC$C0MP0SE_KEY <'a/0/>,<"a/7> 
VC$C0MP0SE_KEY <“a/0/>,<‘a\/\> 
VC$C0MP0SE_KEY <‘a/0/>,<‘a/C/> 
VC$C0MP0SE_KEY <‘a/0/>.<‘a/E/> 
VC$COMPOSE_KEY <‘a/0/>,<*a/S/> 
VC$C0MP0SE_KEY <“a/0/>,<'a/X/> 
VC$C0MP0SE_KEY <‘a/0/>,<*a/*/> 
VC$C0MP0SE_KEY <‘a/0/>,<‘a/_/> 
VC$COMPOSE_KEY <‘a/0/>,<‘a/7> 
VC$C0MP0SE_KEY <'‘a/0/>,<*a/"/> 
VC$C0MP0SE_KEY <“a/0/>,<‘x80>. 

VC$C0MP0SE_KEY <‘a/P/>,<‘a/!/> 

VC$C0MP0SE_KEY <‘a/S/>.<‘a/!/> 
VC$C0MP0SE_KEY <‘a/S/>,<*a/0/> 
VC$C0MP0SE_KEY <'a/S/>,< * a/0/> 

VC$C0MP0SE_KEY <"a/U/>,<*a/"/> 
VC$C0MP0SE_KEY <"a/U/>,<*a/7> 
VC$C0MP0SE_KEY <*a/U/>.<*a/*/> 
VC$C0MP0SE_KEY <*a/U/>,<*a/7> 
VC$C0MP0SE_KEY <‘a/U/>,<'x80>. 

VC$C0MP0SE_KEY <‘a/X/>,<‘a/0/> 
VC$C0MP0SE_KEY <‘a/X/>,<‘a/0/> 

VC$COMPOSE_KEY <-'a/Y/>, <"a/"/> 
VC$C0MP0SE_KEY <‘a/Y/>,<‘a/-/> 
VC$C0MP0SE_KEY <"a/Y/>,<-a/=/> 
VC$C0MP0SE_KEY <“a/Y/>.<*x80>. 


,<"xcb> 

,<"xc9> 

,<"xca> 

,<"xc8> 

<"xcb> 

,<'‘xcf> 

,<"xcd> 

,<"xce> 

,<"xcc> 

<"xcf> 

,<^xa3> 

,<"xa3> 

,<"xdl> 

,<^xd6> 

.<^xd3> 

,<"xd8> 

,<"xa9> 

,<'‘xd7> ; order sensitive 

,<"xa7> 

,<"xa8> 

,<"xd4> 

,<"xba> 

.<''xd2> 

,<"xd5> 

<^xd6> 

,<^xb6> 

,<"xa7> 

.<"xa7> 

,<"xa7> 

,<"xdc> 

,<"xda> 

,<"xdb> 

,<"xd9> 

<"xdc> 

,<"xa8> 

,<"xa8> 

,<"xdd> 

,<"xa5> 

,<"xa5> 

<"xdd> 
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VC$COMPOSE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$COMPOSE_KEY 

VC$COMPOSE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$CDMPOSE_KEY 

VC$C0MP0SE_KEY 

VC$CDMPOSE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$COMPOSE_KEY 

VC$COMPOSE_KEY 


<~a/'/>,<"a/ /> 
<~a/‘/>,<"a/./> 
<*a/*/>.<*a\/\> 
<~a/‘/>.<“a/0/> 
<‘a/“/>.<"a/l/> 
<‘a/*/>.<“a/2/> 
<“a/“/>.<"a/3/> 
<‘a/*/>,<~a/A/> 
<‘a/*/>,<~a/E/> 
<'‘a/~/>,<~a/I/> 
<“a/“/>.<*a/0/> 
<~a/‘/>,<"a/U/> 
<''a/*/>,<'a/a/> 
<“a/*/>,<‘a/e/> 
<*a/‘/>,<''a/i/> 
<“a/“/>,<~a/o/> 
<“a/“/>.<*a/u/> 


<~> 

.<*xb7> 

,<‘a/|/> 

,<“xbO> 

,<*xb9> 

,<'‘xb2> 

,<*xb3> 

,<*xc2> 

,<*xca> 

.<“xce> 

,<*xd4> 

,<*xdb> 

.<"xe2> 

,<*xea> 

,<'‘xee> 

,<“xf4> 

.<“xfb> 


VC$COMPOSE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$COMPOSE_KEY 


<''a/_/>.<~a/A/> 

<*a/_/>,<*a/0/> 

<~a/_/>,<“a/a/> 

<“a/_/>,<“a/o/> 


,<“xaa> 
,<''xba> 
,<“xaa> 
,<"xba> 


VC$C0MP0SE_KEY 

VC$COMPOSE_KEY 

VC$COMPOSE_KEY 

VC$C0MP0SE_KEY 

VC$COMPOSE_KEY 

VC$C0MP0SE_KEY 

VC$COMPOSE_KEY 

VC$COMPOSE_KEY 

VC$COMPOSE_KEY 

VC$CGMPOSE_KEY 


<*a/‘/>,<'a/A/> 

<‘a/‘/>.<"a/E/> 

<“a/‘/>.<“a/I/> 

<~a/‘/>,<"a/0/> 

<“a/‘/>.<“a/U/> 

<“a/‘/>.<“a/a/> 

<*a/‘/>.<'a/e/> 

<*a/‘/>.<“a/i/> 

<~a/‘/>.<“a/o/> 

<‘a/‘/>.<*a/u/> 


,<~xcO> 

,<"xc8> 

,<“xcc> 

,<“xd2> 

.<“xd9> 

,<*xeO> 

,<*xe8> 

,<“xec> 

,<*xf2> 

,<*xf9> 
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a to z 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$COMPOSE_KEY 

VC$COMPOSE_KEY 

VC$COMPOSE_KEY 

VC$COMPOSE_KEY 

VC$COMPOSE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$COMPOSE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$COMPOSE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$COMPOSE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$COMPOSE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$COMPOSE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$COMPOSE_KEY 

VC$COMPOSE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 


<“a/a/>,<*a/"/>,,<"xe4> 
<''a/a/>,<*a/’/>, ,<~xel> 
<*a/a/>,<*a/*/>,,<*xe5> 
<*a/a/>.<''a/“/>. .<"xe2> 
<*a/a/>.<“a/_/>, ,<''xaa> 
<~a/a/>, <'‘a/ ‘ , <*xeO> 

<‘a/a/>, <*a/a/>, <(3> 
<‘a/a/>,<"a/e/>,,<“xe6> 
<~a/a/>.<*a/"/>.,<"xe3> 
<~a/a/>,<"x80>,,<‘xe4> 
<"a/a/>, <''xbO>,, <*xe5> 

<*a/c/>, <''a/. />., <“xe7> 
<"a/c/>,<*a\A>. ,<‘xa2> 
<*a/c/>,<“a/0/>, ,<~xa.9> 
<"a/c/>,<"a/o/>,,<“xa9> 
<~a/c/>,<“a/|/>,,<‘xa2> 

<''a/e/>,<“a/"/>. ,<'‘xeb> 
<*a/e/>,<~a/’/>..<*xe9> 
<~a/e/>,<“a/*/>,,<‘xea> 
<“a/e/>,<''a/‘/>, ,<“xe8> 
<*a/e/>,<*x80>,.<“xeb> 

<“a/i/>,<*a/"/>,.<“xef> 
<“a/i/>,<“a/’/>.,<'xed> 
<'‘a/i/>,<*a/*/>, ,<“xee> 
<“&/ i/>,<“a/‘.<*xec> 
<*a/i/>,<*x80>,,<"xef> 

<*a/l/>.<*a/-/>.,<*xa3> 
<''a/l/>,<*a/=/>, ,<~xa3> 
<"a/l/>.<*a/“/>.,<~xb9> 

<''a/n/>,<*a/"/>, ,<“xfl> 

<‘a/o/>,<“a/"/>, ,<''xf6> 
<“a/o/>,<"a/’/>..<“xf3> 
<*a/o/>,<*a\/\>.,<*xf8> 
<“a/o/>,<“a/*/>,.<*xf4> 
<''a/o/>,<“a/_/>, ,<"xba> 
<*a/o/>,<"a/‘.<“xf2> 
<*a/o/>,<*a/c/>,,<~xa9> 
<“a/o/>,<*a/e/>, ,<''xf7> 
<''a/o/>,<''a/s/>, ,<‘xa7> 
<~a/o/>,<'a/x/>,,<*xa8> 
<*a/o/>,<"a/~/>, ,<'‘xf5> 
<*a/o/>,<*x80>,,<‘xf6> 


order sensitive 


order sensitive 
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VC$COMPOSE_KEY 

VC$C0MP0SE_KEY 

VC$COMPOSE_KEY 

VC$C0MP0SE_KEY 

VC$COMPOSE_KEY 

VC$C0MP0SE_KEY 

VC$COMPOSE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$COMPOSE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 


{ I } - 

VC$COMPOSE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$COMPOSE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$COMPOSE_KEY 


Diaeresis mark 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE^KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 

VC$C0MP0SE_KEY 


<"a/p/>,<"a/!/>,,<"xb6> 

<"a/s/>,<"a/!/>,.<"xa7> 
<^a/s/>.<^a/0/>.,<^xa7> 
<"a/s/>,<"a/o/>,,<"xa7> 
<"a/s/>,<"a/s/>,,<"xdf> 

<"a/u/>,<"a/''/>, ,<"xfc> 
<"a/u/>, <"a/ V>,, <"xf a> 
<"a/u/>,<"a/"/>,,<"xfb> 
<"a/u/>.<"a/‘,<"xf9> 
<"a/u/>,<"x80>,,<"xfc> 

<"a/x/>,<"a/0/>,,<"xa8> 
<"a/x/>,<"a/o/>,,<"xa8> 

<"a/y/>,<"a/*'/>, ,<"xfd> 
<"a/y/>,<"a/-/>, ,<'"xa5> 
<''a/y/>,<"a/=/>, ,<"xa5> 
<"a/y/>,<"x80>,,<"xfd> 


<"a/1 />, <"a/C/>,.<'‘xa2> 
<"a/I/>,<"a/c/>,,<"xa2> 

<^a/~/>,<^a/ />,,<''a/~/> 
<''a/~/>,<"a/A/>, ,<"xc3> 
<"a/~/>,<''a/N/>, ,<"xdl> 
<"a/~/>,<"a/0/>,,<"xd5> 
<"a/~/>,<"a/a/>,,<"xe3> 
<"a/~/>,<"a/n/>,,<"xfl> 
<'‘a/~/>,<"a/o/>, ,<"xf5> 


<"x80>,<"a/A/>,,<"xc4> 
<‘'x80>,<"a/E/>. .<'‘xcb> 
<"x80>,<"a/I/>,,<"xcf> 
<"x80>,<"a/0/>,,<"xd6> 
<''x80>,<"a/U/>, ,<"xdc> 
<"x80>,<"a/Y/>,,<"xdd> 
<"x80>,<"a/a/>,,<"xe4> 
<"x80>,<"a/e/>,,<"xeb> 
<"x80>,<"a/i/>, ,<'‘xef> 
<''x80>,<"a/o/>, ,<"xf6> 
<"x80>,<"a/u/>,,<"xfc> 
<"x80>,<"a/y/>,,<"xfd> 
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Degree sign 

VC$C0MP0SE_KEY <*xbO>,<“a/ />,.<*xbO> 

VC$C0MP0SE_KEY <*xbO>.<‘a/A/>..<‘xc5> 

VC$C0MP0SE_KEY <-xbO>,<'a/a/>,.<*xe5> 

VC$COMPOSE_KEYEND ; END THE TABLE 
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$QIO System Service Description 


$QIO System Service 


The Queue I/O Request service queues an I/O request to a channel 
associated with a device. 

The $QIO service completes asynchronously; that is, it returns to the caller 
immediately after queuing the I/O request, without waiting for the I/O 
operation to complete. 

For synchronous completion, use the Queue I/O Request and Wait ($QIOW) 
service. The $QIOW service is identical to the $QIO service in every 
way except that $QIOW returns to the caller after the I/O operation has 
completed. 


Format 

SYS$QIO [efn] ,chan ,func [Josh] [,astadr] [,astprm] 
[,p1] [,p2] [,p3] [,p4] [,p5] [,p6] 


Returns 


VMS Usage: 
type: 
access: 
mechanism: 


cond—value 
longword (unsigned) 
write only 
by value 


Longword condition value. All system services return (by value) a condition 
value in RO. Condition values that can be returned by this service are listed 


under "CONDITION VALUES RETURNED." 
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Arguments 

efn 

VMS Usage: ef—number 
type: longword (unsigned) 

access: read only 

mechanism: by value 

Event flag that $QIO is to set when the I/O operation actually completes. 
The efn argument is a longword value containing the number of the event 
flag. 

If efn is not specified, event flag 0 is set. 

When $QIO begins execution, it clears the specified event flag or event flag 0 
if efn was not specified. 

The specified event flag is set if the service terminates without queuing an 
I/O request. 

chan 

VMS Usage: channel 
type: word (unsigned) 

access: read only 

mechanism: by value 

I/O channel that is assigned to the device to which the request is directed. 
The chan argument is a word value containing the number of the I/O 
channel; however, $QIO uses only the low-order word. 

func 

VMS Usage: function_code 
type: word (unsigned) 

access: read only 

mechanism: by value 

Device-specific function codes and function modifiers specifying the 
operation to be performed. The func is a longword value containing the 
function code. 

Each device has its own function codes and function modifiers. Refer to 
Chapter 3 and Chapter 4 for complete information about the function codes 
and function modifiers that apply to the particular I/O operation you want 
to perform. 
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iosb 


VMS Usage: 
type: 
access: 
mechanism: 


io-.status^biock 
quadword (unsigned) 
write only 
by reference 


I/O status block to receive the final completion status of the I/O operation. 
The iosb is the address of the quadword I/O status block. The following 
diagram depicts the structure of the I/O status block: 


31 15 0 


transfer count 

condition value 


device-specific information 


I/O Status Block Fields 

condition vaiue 


ZK-1723-84 


Word-length condition value returned by $QIO when the I/O 
operation actually completes. 

transfer count 

Number of bytes of data actually transferred in the I/O operation. 

device^specific information 

The contents of this field vary depending on the specific device and 
on the specified function code. 

When $QIO begins execution, it clears the quadword I/O status block if the 
iosb argument is specified. 

Though this argument is optional, DIGITAL strongly recommends that you 
specify it for the following reasons. 

• If you are using an event flag to signal the completion of the service, you 
can test the I/O status block for a condition value to be sure that the 
event flag was not set by an event other than service completion. 

• If you are using the $SYNCH service to synchronize completion of the 
service, the I/O status block is a required argument for $SYNCH. 
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• The condition value returned in RO and the condition value returned 
in the I/O status block provide information about different aspects of 
the call to the $QIO service. The condition value returned in RO gives 
you information about the success or failure of the service call itself; the 
condition value returned in the I/O status block gives you information 
about the success or failure of the service operation. Therefore, to 
accurately assess the success or failure of the call to $QIO, you must 
check the condition values returned in both RO and the I/O status block. 


astadr 


VMS Usage: 
type: 
access: 
mechanism: 


ast—procedure 
procedure entry mask 
call without stack unwinding 
by reference 


AST service routine to be executed when the I/O completes. The astadr 
argument is the address of a longword value that is the entry mask to the 
AST routine. 


The AST routine executes at the access mode of the caller of $QIO. 


astprm 

VMS Usage: 
type: 
access: 
mechanism: 


user..arg 

longword (unsigned) 
read only 
by value 


AST parameter to be passed to the AST service routine. The astprm 
argument is a longword value containing the AST parameter. 


pi to p6 

VMS Usage: 
type: 
access: 
mechanism: 


varying—arg 
longword (unsigned) 
read only 
by reference 


Optional device- and function-specific I/O request parameters. For more 
information on these parameters see the individual QIO descriptions 
contained in Chapters 3 and 4. 


Description 

$QIO operates only on assigned I/O channels and only from access modes 
that are equal to or more privileged than the access mode from which the 
original channel assignment was made. 
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$QIO uses the following system resources: 

• The process' quota for buffered I/O limit (BIOLM) or direct I/O limit 
(DIOLM). 

• The process' buffered I/O byte count (BYTLM) quota. 

• The process' AST limit (ASTLM) quota, if an AST service routine is 
specified. 

• System dynamic memory is required to construct a data base to queue 
the I/O request. 

• Additional memory may be required on a device-dependent basis. 

For $QIO, completion can be synchronized by (1) specifying the astadr 
argument to have an AST routine execute when the I/O completes or (2) 
by calling the Synchronize ($SYNCH) service to await completion of the I/O 
operation. $QIOW completes synchronously, and it is the best choice when 
synchronous completion is required. 


Return Values 

SS$_NORMAL 

SS$_ABORT 

SS$__ACCVIO 

SS$_DEVOFFLINE 

SS$_EXQUOTA 


Service successfully completed. The I/O request was 
successfully queued. 

A network logical link was broken. 

Either the I/O status block cannot be written by 
the caller, or the parameters for device-dependent 
function codes are incorrectly specified. 

The specified device is offline and not currently 
available for use. 

The process has (1) exceeded its AST limit (ASTLM) 
quota, (2) exceeded its buffered I/O byte count 
(BYTLM) quota, (3) exceeded its buffered I/O limit 
(BIOLM) quota, (4) exceeded its direct I/O limit 
(DIOLM) quota, or (5) requested a buffered I/O 
transfer smaller than the buffered byte count quota 
limit (BYTLM), but when added to other current 
buffer requests, the buffered I/O byte count quota 
was exceeded. 
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SS$_ILLEFC 

SS$_INSFMEM 

SS$_IVCHAN 


SS$_NOPRIV 


SS$_UNASEFC 

SS$_LINKABORT 

SS$_LINKDISCON 

SS$_PATHLOST 

SS$_PROTOCOL 

SS$_CONNECFAIL 

SS$_FILALRACC 

SS$_INVLOGIN 

SS$_IVDEVNAM 

SS$_LINKEXIT 


SS$_NOLINKS 


SS$_NOSUCHNODE 

SS$_NOSUCHOBJ 


SS$_NOSUCHUSER 


An illegal event flag number was specified. 

Insufficient system dynamic memory is available to 
complete the service. 

An invalid channel number was specified, that is, 
a channel number of 0 or a number larger than the 
number of channels available. 

The specified channel does not exist, was assigned 
from a more privileged access mode, or the process 
does not have the necessary privileges to perform the 
specified functions on the device associated with the 
specified channel. 

The process is not associated with the cluster 
containing the specified event flag. 

The network partner task aborted the logical link. 

The network partner task disconnected the logical 
link. 

The path to the network partner task node was lost. 

A network protocol error occurred. This is most 
likely due to a network software error. 

The connection to a network object timed out or 
failed. 

A logical link is already accessed on the channel 
(that is, a previous connect on the channel). 

The access control information was found to be 
invalid at the remote node. 

The NCB has an invalid format or content. 

The network partner task was started, but exited 
before confirming the logical link (that is, $ASSIGN 
to SYS$NET). 

No logical links are available. The maximum number 
of logical links as set for the executor MAXIMUM 
LINKS parameter was exceeded. 

The specified node is unknown. 

The network object number is unknown at the 
remote node; or for a TASK = connect, the named 
DCL command procedure file cannot be found at the 
remote node. 

The remote node could not recognize the login 
information supplied with the connection request. 
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SS$_PROTOCOL 

SS$_REJECT 

SS$_REMRSRC 

SS$_SHUT 

SS$_THIRDPARTY 

SS$_TOOMUCHDATA 

SS$_UNREACHABLE 


A network protocol error occurred. This error is most 
likely due to a network software error. 

The network object rejected the connection. 

The link could not be established because system 
resources at the remote node were insufficient. 

The local or remote node is no longer accepting 
connections. 

The logical link was terminated by a third party (for 
example, the System Manager). 

The task specified too much optional or interrupt 
data. 

The remote node is currently unreachable. 


Condition Vaiues Returned in the 

Device-specific condition values. 


I/O Status Block 







Appendix I 

DEC Multinational Character Set 


The table below represents the ASCII character set (characters with decimal values 0 
through 127). The first half of each of the numbered columns identifies the character 
as you would enter it on a VT200 or VTIOO series terminal or as you would see it on 
a printer (except for the nonprintable characters). The remaining half of each column 
identifies the character by the binary value of the byte; the value is stated in three 
radixes—octal, decimal, and hexadecimal. For example, the letter uppercase A has, 
under ASCII conventions, a storage value of hexadecimal 41 (a bit configuration of 
01000001), equivalent to 101 in octal notation and 65 in decimal notation. 
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COLUMN 

0 

1 
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3 

4 

5 

6 

7 

■ 
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b7 

h6 
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b4 1)3 b2 b1 

0 

0 

0 

0 

0 

0 

0 

1 

0 

0 

0 

0 

0 

1 

0 

1 

0 

0 

0 

1 

0 

0 

1 ^ 

0 

0 

1 

0 

0 0 0 0 

NUL 

0 

0 

0 

OLE 

20 

16 

10 

SP 

40 

32 

20 

0 

60 

48 

30 

@ 

100 

64 

40 

p 

120 

80 

50 

\ 

140 

96 

60 

p 

160 

112 

70 

1 

0 0 0 1 

SOH 

1 

1 

1 

DC1 

(XON) 

21 

17 

11 

! 

41 

33 

21 

1 

61 

49 

31 

A 


Q 

121 

81 

51 

a 

141 

97 

61 

q 

161 

113 

71 

2 

0 0 10 

STX 

2 

2 

2 

DC2 

22 

18 

12 

11 

42 

34 

22 

2 

62 

50 

32 

B 

102 

66 

42 

R 

122 

82 

52 

b 

142 

98 

62 

r 

162 

114 

72 

3 

0 0 11 

ETX 

3 

3 

3 

DC3 

(XOFF) 

23 

19 

13 

# 

43 

35 

23 

3 

63 

51 

33 

C 


S 

123 

83 

53 

c 

143 

99 

63 

s 

163 

115 

73 

4 

0 10 0 

EOT 

4 

4 

4 

DC4 

24 

20 

14 

$ 

44 

36 

24 

4 

64 

52 

34 

D 

1 

T 

124 

84 

54 

d 

144 
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64 

t 

164 

116 

74 

5 
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ENQ 

5 

5 

5 

NAK 

25 

21 

15 

% 

45 

37 

25 

5 

65 

53 

35 

E 

105 

69 

45 

U 

125 

85 

55 

e 

145 

101 

65 

u 

165 

117 

75 

6 

0 110 

ACK 

6 

6 

6 

SYN 

26 

22 

16 

& 

46 

38 

26 

6 

66 

54 

36 

F 
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70 

46 

V 

M 

f 

146 

102 

66 

V 

166 

118 

76 

7 

0 111 

BEL 

7 

7 

7 

ETB 

27 

23 

17 

/ 

47 

39 

27 

7 

67 

55 

37 

G 

107 

71 

47 
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147 

103 

67 

w 

167 

119 

77 

8 

10 0 0 

BS 

10 

8 

8 

CAN 

30 

24 

18 

( 

50 

40 

28 

8 

70 

56 

38 

H 

110 

72 

48 

D 

1 

h 

150 

104 

68 

X 
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78 

9 

10 0 1 

HT 

11 

9 

9 

EM 

31 

25 

19 

) 

51 

41 

29 

9 

71 

57 

39 

1 
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73 

49 

Y 

m 

i 
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69 

y 

171 
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79 

10 
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LF 

12 

10 

A 
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26 

1A 

* 

52 

42 

2A 

: 

72 

58 

3A 

J 
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74 

4A 

Z 
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90 

5A 

j 
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6A 

z 
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7A 

11 
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VT 

13 

11 

B 
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33 

27 

18 

+ 

53 

43 

2B 

; 

73 

59 
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75 

4B 

c 
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91 

5B 

k 

153 

107 

6B 

< 
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7B 

12 
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FF 
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12 

C 
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34 

28 

1C 

, 

54 

44 

2C 

< 
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76 

4C 

\ 
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92 

5C 

1 
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6C 

1 
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7C 

13 
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CR 

15 

13 

D 

GS 

35 

29 

ID 


55 

45 

2D 


75 

61 

3D 


115 

77 

4D 

] 
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93 

5D 

m 
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6D 

> 
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7D 

14 
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SO 

16 

14 

E 

RS 

36 

30 

IE 


56 

46 

2E 

> 

76 

62 

3E 

N 
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78 

4E 

A 
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5E 

n 
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6E 
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7E 

15 

1111 

SI 

17 

15 

F 

US 

37 

31 

IF 

/ 

57 

47 

2F 

7 

77 

63 

3F 

0 

117 

79 

4F 

— 

137 

95 

5F 

0 

157 

in 

6F 

DEL 

177 

127 

7F 


KEY 


ESC 

33 

27 
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DEC Multinational Character Set i-3 


The ASCII character set comprises the first half of the DEC multinational character 
set. The following table represents the second half of the DEC multinational 
character set (characters with decimal values 128 through 255). The first half of 
each of the numbered columns identifies the character as you would see it on a 
VT200 series terminal or printer (these characters cannot be output on a VTIOO series 
terminal). 
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10 11 12 13 




201 

129 PU1 


202 I 

130 PU2 


203 

,31 STS 


204 I 

132 CCH 


205 

133 MW 


206 

134 SPA 


213 

139 CSI 


214 

140 ST 


215 I 

141 osc 


216 

142 PM 
8E 

217 

143 APC 


14 

1 

1 

0 

a 

340 

224 

EO 

a 

341 

225 

El 

A 

a 

342 

226 

E2 


343 

227 

E3 

*a" 

344 

228 




360 

240 0 0 0 0 0 

FO _ 

361 

241 0 0 0 1 1 

FI 

362 

242 0010 


363 I 

243 001 1 


364 I 

244 I 0 1 00 


365 I 

245 I 0 1 0 1 


366 

246 I 01 10 


367 

247 0 1 1 1 

F7 _ 

370 I 

248 1 0 0 0 I 8 


249 I 1001 


250 1 0 1 0 in 

FA 

373 

251 10 11 11 


252 1 1 0 0 I 12 


375 

253 1 1 0 1 I 13 


254 I 1 1 1 0 I 14 


1111 15 
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Index 

A 

Absolute device coordinates 
See ADC 

ADC (absolute device coordinates), 1-16, 
2-31, 2-39 

B 

Background color index, 5-24 
Bitmap 

accessing, 1-9, 1-11 

exclusive access to, 2-39 

loading into offscreen memory, 2-35 

loading into storage area, 1-11 

reading, 2-35 

storage area, 1-11 

systemwide, 4-22 

transferring, 1-11 

writing, 2-35 

Bitmap—glyphs field, 5-27 
Bitmap—ID field, 5-27 
Bitmap ID, 2-35 
Button simulation block, A-2 
Button transition value, 2-25 

C 

Channel 

assigning, 2-3 
assigning to viewport, 2-30 
deassigning, 2-51 
Character 

composing nonstandard, 2-14 
input, 2-25 


Color 

displaying, 2-58 
identifing system type, 2-58 
Color map 

changing values in, 2-59 
Compose sequence, 2-14 
three-stroke, 2-14 
two-stroke, 2-14 
Compose sequence table, 2-15 
constructing, 2-15 
default, 2-19 
initializing, 2-18 
loading, 2-19 
macro to generate, F-1 
terminating, 2-19 
three-stroke, 2-15 
two-stroke, 2-16 
Control AST, 2-5 
Cursor hot spot structure, A-3 
Cursor pattern 
defining, 2-26 
multiplane, 2-28, 3-6 
Cursor pattern entry 
creating, 2-26 
Cursor pattern list, 1-13 
Cycling operation, 1-13 

D 

Data rectangle values block, A-3 
Data type 

using predefined structure, A-1, B-1 
DEC multinational character set, I-l 
Deferred queue, 1-19 
deleting, 2-58 
executing, 2-57 
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Define Pointer Cursor Pattern QIO, 1-13, 

2-26, 3-3 

Define Viewport Region QIO, 2-31, 2-39, 
2-40, 2-57, 4-3 
Delete Bitmap DOP, 5-29 
Delete Deferred Queue Operation QIO, 

2-58, 4-6 

Diacritical mark, 2-11, 2-14, 2-16 

Diacritical table, 2-16 

DOP (drawing operation primitive), 1-7, 

5-1 to 5-101 

allocating memory for, 1-18 
allocating storage for, 5-3 
drawing with, 2-35 
entering on request queue, 1-17 
executing, 5-6 

asynchronously, 5-6 
initializing, 5-13 to 5-18 

using predefined structure, 5-17 
large, 5-5 
small, 5-5 
state of, 2-36 
structuring, 5-13 to 5-18 

using predefined structure, 5-17 
Dop_line_array predefined structure, 5-51 
Dop_move^array predefined structure, 

5-64, 5-78 

Dop^move_r-_array predefined structure, 
5-30, 5-69 

Dop_point_array predefined structure, 

5-55 

Dop_poly_array predefined structure, 5-59 
Dop—Structure predefined structure, 5-20 
Dop_vtext_array predefined structure, 5-46 
DOP Common block, 5-2, 5-14, 5-20 
initializing, 5-23 to 5-28 
DOP queue structure, B-2 
DOP Unique block, 5-3, 5-16 
DOP Variable block, 5-3, 5-16 
Draw Complex Line DOP, 5-30 
Draw Fixed Text DOP, 5-35 
Drawing operation primitive 
See DOP 

Draw Lines DOP, 5-39 
Draw Points DOP, 5-43 
Draw Variable Text DOP, 5-46 


E 

Enable Button Transition QIO, 1-14, 2-22, 

3-9 

Enable Data Digitizing QIO, 3-15 
Enable Function Keys QIO, 3-20 
Enable Input Simulation QIO, 3-23 
Enable Keyboard Input QIO, 1-13, 2-4, 2-8, 
3-26 

Enable Keyboard Sound QIO, 3-34 
Enable Pointer Movement QIO, 1-15, 2-21, 

3- 36 

Enable User Entry QIO, 3-41 
Example 

assign channel, 2-5 
AST routine, 2-5 
keyboard request, 2-5 
QVSS sample program, D-1 
Execute Deferred Queue QIO, 1-19, 2-57, 

4- 7 

Exit AST, 2-21 

F 

Fill Lines DOP, 5-51 
Fill Point DOP, 5-55 
Fill Polygon DOP, 2-51, 5-59 
Flags field, 5-28 
Foreground color index, 5-24 
Free_l area, 1-11, 2-39 
Free DOP, 1-18 

G 

Get Color Map Entries QIO, 2-59, 4-8 
Get Free DOPs QIO, 1-18, 4-10 
Get Keyboard Characteristics QIO, 1-6, 
3-43 

Get Next Input Token QIO, 2-4, 2-26, 3-46 
Get Number of List Entries QIO, 3-47 
Get System Information QIO, 1-12, 2-2, 
2-51, 3-48 

Get Viewport ID QIO, 1-17, 2-31, 4-12 
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H 

Hardware color map, 2-58, 2-59 
determining current values of, 2-59 
loading values into, 2-59 

Hardware cursor, 1-8 

Hardware look-up table, 2-58 

Hold Viewport Activity QIO, 2-37, 4-15 

I 

Image 

drawing, 2-36 
storing, 2-36 

Initialize Screen QIO, 2-1, 3-49 

Input 

intercepting, 2-26 

Insert DOP QIO, 1-17, 2-37, 2-51, 4-16 

INSQUE (Insert Entry in Queue) instruction, 
5-11 

Intensity value, 2-58 

IO$_QV_TWO_PLANE_CURSOR function 
modifier, 3-4 

IO$_QV_USE-DEFAULT function 
modifier, 3-4 

IO$C_QD_COLOR_CHAR function code, 
4-30 

IO$C_QD_DELETE_DEFERRED function 
code, 4-6 

IO$C_QD_EXECUTE_DEFERRED function 
code, 4-7 

IO$C_QD_«GET_COLOR function code, 

4-8 

IO$C_QD_GET_FREE_DOPS function 
code, 4-10 

IO$C_QD^GET_-VIEWPORT-JD function 
code, 4-12 

IO$C_QD_HOLD function code, 4-15, 

4-23 

IO$C-_QD^LOAD_BITMAP function code, 
4-18 

IO$C_QD_NOHOLD function code, 4-28 

IO$C_QD_OCCLUDED_SUSPEND 
function code, 4-35 


IO$C_QD_RESUME_VP function code, 
4-29 

IO$C_QD_SET_VIEWPORT_REGIONS 
function code, 4-3 

IO$C_QD_SET_COLOR function code, 

4-31 

IO$C_QD^START function code, 4-33 
IO$C_QD_STOP function code, 4-34 
IO$C_QD«SUSPEND_VP function code, 
4-36 

IO$C_QV_>ENABLE_DIGITIZING function 
code, 3-15 

IO$C_QV_ENABUTTON function code, 

3-9 

IO$C_QV_ENAFNKEY function code, 3-20 
IO$C_QV_ENAKB function code, 3-26 
IO$C_QV_ENAUSER function code, 3-41 
IO$C_QV_GET_ENTRIES function code, 
3-47 

IO$C_QV_GETKB_INFO function code, 
3-43 

IO$C_QV_GETSYS function code, 3-48 
IO$C_QV_INITIALIZE, 3-49 
IO$C_QV_LOAD__COMPOSE_TABLE 
function code, 3-50 

IO$C_QV_LOAD_KEY_TABLE function 
code, 3-53 

IO$C_-QV_MODIFYKB function code, 3-55 
IO$C_QV__MODIFYSYS function code, 

3-60 

IO$C_QV_MOUSEMOV function code, 

3- 36 

IO$C_QV_SETCURSOR function code, 3-3 
IO$C_QV_SIMULATE function code, 3-23 
IO$C_QV_SOUND function code, 3-34 
IO$C-.QV_USE_DEFAULT_TABLE 
function code, 3-65, 3-66 
IO$M_QD_INTENSITY function modifier, 

4- 8, 4-31 

IO$M->QD_SYSTEM_WIDE function 
modifier, 4-18 

IO$M_QV_ACTIVE function modifier, 3-55 
IO$M_QV_BIND function modifier, 3-3 
IO$M_QV_COMPOSE2 function modifier, 
3-65 
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IO$M-_QV-_COMPOSE3 function modifier, 
3-65 

IO$M—Q\L.CYCLE function modifier, 3-26, 
3-41 

IO$M—QV—DELETE function modifier, 3-3, 
3-9, 3-15, 3-26, 3-36, 3-41 
IO$M^QV_JCEYS function modifier, 3-66 
IO$M—Q\L.LAST function modifier, 3-3, 
3-9, 3-26, 3-36, 3-41 
IO$M_QV-LOAD__DEFAULT function 
modifier, 3-4, 3-50, 3-53 
IO$M^QV-«PURG—TAH function modifier, 
3-9, 3-26 

IO$M__RESERVED-_COLORS function 
modifier, 4-8, 4-31 
item^type field, 5-24 

K 

Key 

defining, 2-9 
Keyboard 

activating, 1-13 
cycling, 1-13 
popping, 1-13 
programming, 2-9 
receiving input from, 2-4 
using, 2-4 to 2-20 
virtual, 2-5 

Keyboard characteristics, 2-7 
defining, 2-8 

Keyboard characteristics block, 2-5, A-5 
Keyboard entry list, 1-13, 2-4 
Keyboard request AST specification block, 
A-4 

Keyboard table 
constructing, 2-12 
initializing, 2-9 
loading, 2-9, 2-13 
macro to generate, E-1 
modifying, 2-9 
terminating, 2-11 
Key-click volume, 2-8 
Keystroke AST specification block, A-7 


L 

LIB$GET_VM, 5-8 

List entry, 1-5, 1-12 

Load Bitmap QIO, 1-11, 2-36, 4-18 

Load Compose Sequence Table QIO, 2-15, 

2- 19, 3-50 

Load Keyboard Table QIO, 2-9, 2-13, 3-53 

M 

Macro 

compose table, F-1 
keyboard table, E-1 
Memory 

offscreen, 1-7, 1-10, 1-17 
onscreen, 1-7, 1-10, 1-17 
Meta-key, 2-23, 3-11, 3-18, 3-27 
Modify Keyboard Characteristics QIO, 2-8, 

3- 55 

Modify Systemwide Characteristics QIO, 
2-8, 3-60 
Mouse, 2-21 

Move/Rotate Area DOP, 5-69 
Move Area DOP, 5-64 

N 

New cursor position structure. A-11 
New pointer position structure, A-11 
Notify Deferred Queue Full QIO, 1-19, 
2-57, 4-23 

O 

Occlusion, 1-15, 1-19 
handling, 2-38 

handling with update regions, 1-17 
Offscreen memory, 1-7, 1-10, 1-17, 2-39 
Onscreen memory, 1-7, 1-10, 1-17 
Opcount field, 5-24 
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P 

Plot^args predefined structure, 5-39, 5-43, 
5-51, 5-55, 5-59 
Pointer, 2-21 
using, 2-20 

Pointer button characteristics block, A-8 
Pointer button transition, 2-20 
creating entry, 2-22 
Pointer button transition list, 1-14 
Pointer characteristics block, A-9 
Pointer motion AST specification block, 
A-10 

Pointer movement, 2-20 
creating entry, 2-21 
Pointer movement list, 1-15 
Pointer movement list entry, 2-21 
Pointer position, 2-25 
Popping operation, 1-13 
Puck, 2-21 

Q 

QDB (QDSS block) structure, B-3 
QDSS block 
See QDB 

QIO interface, 1-5 
QVB (QVSS block) structure. A-12 
Qvb_common ..structure. A-12 
Qvb_qdss_structure predefined structure, 
B-3 

QVSS block 
See QVB 

QVSS control driver 
sample program, D-1 

R 

Read Bitmap QIO, 1-11, 2-36, 2-39, 2-57, 
4-24 

Region, 1-4 
defining, 1-5 

placing on deferred queue, 2-57 
Region descriptor, 2-21 


Release Hold QIO, 2-37, 4-28 
Req..structure predefined structure, B-2 
Request AST, 2-5 
Request queue, 1-7, 1-17, 5-7 
Reserved function keystroke AST 
specification block. A-17 
Resume Request Queue QIO, 2-37 
Resume Viewport Activity DOP, 2-37, 5-76 
Resume Viewport Activity QIO, 4-29 
Ret_structure predefined structure, B-6 
Return queue, 1-18, 5-5 
alternate, 1-19 
Return queue structure, B-6 
Revert to Default Compose Table QIO, 
2-19, 3-65 

Revert to Default Keyboard Table QIO, 
2-13, 3-66 

S 

Scanline, 2-30 

Scanline map, 1-7, 1-8.1, 1-9, 2-2, 2-30 
obtaining address of base, 2-30 
Screen 

drawing to, 2-29 
initializing, 2-1 

mapping video memory to, 2-30 
writing to, 1-7 
Screen event 
tracking, 1-12 

Screen rectangle values block. A-18 
Screen saver time, 2-8 
Scroll Area DOP, 5-78 
Scrolling save area, 1-11 
Set Color Characteristics QIO, 2-58, 4-30 
Set Color Map Entries QIO, 2-58, 2-59, 
4-31 

Set Viewport Region QIO, 1-16 

Source index, 5-25 

Start Request Queue DOP, 5-83 

Start Request Queue QIO, 2-32, 2-37, 2-40, 

4- 33 

Start Viewport Activity DOP, 2-37 
Stop_args predefined structure, 5-76, 5-83, 

5- 85, 5-87 
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Stop Request Queue DOP, 5-85 
Stop Request Queue QIO, 2-37, 2-39, 4-34 
Stop Viewport Activity DOP, 2-37, 2-51 
Stylus, 2-21 

Suspend Occluded Viewport Activity QIO, 

4- 35 

Suspend Request Queue QIO, 2-37 
Suspend Viewport Activity DOP, 2-37, 5-87 
Suspend Viewport Activity QIO, 4-36 
SYSSASSIGN, 2-3 
SYSSDASSGN, 2-51 
SYS$QIO, H-1 

System characteristics block, 2-7, A-19 
System information block, 1-6, 2-2 
Systemwide viewport, 1-16, 2-30 

T 

Text_args predefined structure, 5-35, 5-46 
Token, 2-23, 3-11, 3-18 
TPB (transfer parameter block), 2-40, B-7 
Tpb_structure predefined structure, B-7 
Transfer parameter block 
See TPB 

Typeahead buffer 

getting input from, 2-25 
purging, 2-25 
using, 2-25 

U 

UIS$CREATE_WINDOW, 5-7 
UISDC$ ALLOC ATE _DOP, 5-3, 5-7, 5-15, 

5- 92 

UISDC$EXECUTE->DOP-^SYNCH, 5-6, 
5-96 

UISDC$EXECUTE^DOP_SYNCH, 5-6, 

5-98 

UISDC$LOADJITMAP, 1-11, 5-94 
UISDC$QUEUE_DOP, 5-6, 5-100 
Update region, 1-16 
and occlusion, 1-17 
defining, 2-31 
Update region definition 
See URD 


Update region definition block, B-9 
URD (update region definition) buffer, 2-31, 
2-39 

Ur(L>structure predefined structure, B-9 
User-defined viewport, 1-16 

V 

VC$KEY, 2-9 
VC$KEYEND, 2-9 
VC$KEYINIT, 2-9 
Video memory 

copying images to, 1-11 
drawing to, 1-11 
driver use of, 1-7 
mapping to screen, 2-30 
private, 2-29 
setting bits in, 2-29 
Viewport, 1-4, 1-11, 1-16 to 1-17 
creating, 2-30 
defining, 2-31 
deleting, 2-51 
erasing, 2-51 
moving, 2-57 
popping, 2-38, 2-44 
redefining, 2-39 
starting, 2-32 

synchronizing activity on, 2-36 
Viewport ID, 1-17, 5-7 
getting, 2-31 

Viewport-relative coordinates 
See VRC 

Viewport request queue, 2-32 
VRC (viewport-relative coordinates), 1-16, 
2-31 

W 

Window ID, 5-7 
Windowing system 

enabling alternate, 2-29 
Write Bitmap QIO, 1-11, 2-36, 2-39, 2-57, 
4-37 

Writing mode, 5-24 
Writing mode field, 5-28 
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i z 

Z-mode, 2-58, 2-59 


( 
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